Expose poe-code skill installation as a public SDK subpath

[kamilio]

Concrete need

poe-agent-tools needs to ship a hidden command named poe-agent-tools install-skill that installs this repository's checked-in skill file into the current project for Codex:

• source skill file: .agents/skills/poe-agent-tools/SKILL.md
• target agent: codex
• target scope: local
• expected installed path: .codex/skills/poe-agent-tools/SKILL.md

This command should call a poe-code SDK function. It should not shell out to poe-code, hand-roll file copies, duplicate path validation, or rely on private package internals.

Current blocker

As of poe-code@3.0.389:

• The package includes internal files under packages/agent-skill-config/dist.
• @poe-code/agent-skill-config is not published as an importable npm package.
• poe-code's exports map exposes only ., ./agent, and ./memory; it does not expose ./skills.

So external repos cannot safely call installSkill without relying on private package internals or duplicating behavior.

SDK contract needed by poe-agent-tools

Please expose a public SDK subpath from poe-code:

{
  "exports": {
    "./skills": {
      "types": "./dist/skills.d.ts",
      "import": "./dist/skills.js"
    }
  }
}

The subpath should export an installSkill helper with this shape:

import { installSkill } from "poe-code/skills";

const result = await installSkill(
  "codex",
  {
    name: "poe-agent-tools",
    file: ".agents/skills/poe-agent-tools/SKILL.md"
  },
  {
    cwd: process.cwd(),
    homeDir: os.homedir(),
    scope: "local",
    dryRun: false
  }
);

// result.displayPath === ".codex/skills/poe-agent-tools/SKILL.md"
// result.skillPath === `${process.cwd()}/.codex/skills/poe-agent-tools/SKILL.md`

The helper should also accept direct content for callers that do not want the SDK to read from a file:

await installSkill(
  "codex",
  { name: "poe-agent-tools", content: skillMarkdown },
  { cwd, homeDir, scope: "local", dryRun }
);

Types needed by callers:

type SkillInstallSource =
  | { name: string; file: string }
  | { name: string; content: string };

type InstallSkillOptions = {
  cwd: string;
  homeDir: string;
  scope: "local" | "global";
  dryRun?: boolean;
};

type InstallSkillResult = {
  displayPath: string;
  skillPath: string;
};

If the implementation needs an injected filesystem for poe-code's own tests, expose that as an optional advanced option. The normal external SDK call must not require importing poe-code's internal FileSystem type.

Required behavior

• scope: "local" installs under ${cwd}/.codex/skills for codex.
• scope: "global" installs under ${homeDir}/.codex/skills for codex.
• file paths are resolved relative to cwd unless absolute.
• name is validated by the same skill-name validation used internally today.
• Existing destination files should fail loudly unless the existing centralized skill machinery deliberately supports overwrite.
• dryRun: true returns the intended path and writes nothing.
• The implementation should continue to rely on @poe-code/agent-skill-config internally so path validation and mutation behavior stay centralized.

How poe-agent-tools will use this

Once this SDK exists, poe-agent-tools will:

1. Add poe-code as a runtime dependency at the released version containing poe-code/skills.
2. Add a hidden handwritten Toolcraft command through handwrittenCommands:

import os from "node:os";
import process from "node:process";
import { defineCommand, S } from "toolcraft";
import { installSkill } from "poe-code/skills";

export const installSkillCommand = defineCommand({
  name: "install-skill",
  hidden: true,
  params: S.Object({}),
  handler: async () => {
    return installSkill(
      "codex",
      {
        name: "poe-agent-tools",
        file: ".agents/skills/poe-agent-tools/SKILL.md"
      },
      {
        cwd: process.cwd(),
        homeDir: os.homedir(),
        scope: "local"
      }
    );
  }
});

3. Include .agents/skills/poe-agent-tools/SKILL.md in the npm package files list.
4. Remove the temporary pre-dispatch shell-out from src/bin/cli.ts.

Acceptance criteria

• npm view poe-code@latest exports --json includes ./skills.
• From a clean external package, this works:

node -e 'import("poe-code/skills").then(m => console.log(Object.keys(m)))'

and prints installSkill.

• A clean external repo can run the SDK example above and create .codex/skills/poe-agent-tools/SKILL.md without importing private subpaths.

[poe-code-agent]

Issue was resolved by #b04c2c3

Update poe-code via npm install -g poe-code@3.0.390

[kamilio]

Checked poe-code@3.0.392 from a clean external package (poe-agent-tools). The export map is present now, but the SDK subpath is not actually usable at runtime.

Repro:

npm install poe-code@3.0.392
node --input-type=module - <<'NODE'
import { installSkill } from 'poe-code/skills';
console.log(typeof installSkill);
NODE

Actual:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@poe-code/agent-skill-config' imported from .../node_modules/poe-code/dist/skills.js

node_modules/poe-code/packages/agent-skill-config/dist/index.js exists inside the package tarball, but dist/skills.js imports @poe-code/agent-skill-config as a bare package. That package is not installed and is not published:

npm view @poe-code/agent-skill-config version
# npm ERR! 404 Not Found

So the remaining release fix needed is one of:

• bundle/rewrite the import in dist/skills.js so it imports the shipped internal file by relative path, or
• publish/install @poe-code/agent-skill-config as a real dependency of poe-code, or
• expose installSkill without any runtime dependency on a private bare workspace package.

The acceptance test should be an external-package import test, not only a monorepo test:

mkdir /tmp/poe-code-skills-smoke && cd /tmp/poe-code-skills-smoke
npm init -y
npm install poe-code@latest
node --input-type=module -e 'import("poe-code/skills").then(m => console.log(typeof m.installSkill))'

Expected output: function.

[kamilio]

Reopening: this is still failing from poe-agent-tools against the current npm latest, poe-code@3.0.392.

Current external-package smoke test:

npm install poe-code@^3.0.392
node --input-type=module - <<'NODE'
import { installSkill } from 'poe-code/skills';
console.log(typeof installSkill);
NODE

Actual error:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@poe-code/agent-skill-config' imported from /Users/kjopek/Workspace/poe-agent-tools/node_modules/poe-code/dist/skills.js

Package state:

npm view poe-code version exports --json
# version: 3.0.392
# exports includes ./skills

npm view @poe-code/agent-skill-config version
# 404 Not Found

So ./skills is exported, but poe-code/dist/skills.js still imports a private bare workspace package that external installs cannot resolve. The external import acceptance criterion is not met yet.

[kamilio]

Verified fixed in poe-code@3.0.393 from poe-agent-tools: import { installSkill } from "poe-code/skills" resolves from an external install and returns function. Wiring poe-agent-tools install-skill to the SDK now.

[kamilio]

Verified fixed in poe-code@3.0.393 from an external package.