skilldrop-cli 0.5.0 → 0.7.0

package/README.md

@@ -285,7 +285,21 @@ npx skilldrop-cli install --agent code-quality --project    # .claude/agents/, s
 
 Then delegate by name: *"use the devils-advocate agent on this diff."*
 
-Only **plain-copy targets** ship today — Claude Code (whose format the file already is) and `--dest <dir>`. Copilot needs a filename change, Kiro a generated JSON wrapper, Codex a schema the survey never confirmed; each of those is a projection waiting on [RFC-0010](docs/rfcs/0010-install-target-table.md), and the CLI says so rather than guessing a path. [`agents/README.md`](agents/README.md) has the manual route for all of them.
+Four targets, each projecting only as much as the tool's format demands:
+
+| Target | Writes | Projection |
+|---|---|---|
+| *(default)* | `~/.claude/agents/<name>.md` | none — the file already is Claude Code's format |
+| `--ide copilot` | `.github/agents/<name>.agent.md` | a rename |
+| `--ide kiro` | `.kiro/agents/<name>.json` | generated JSON; tool names mapped to Kiro's built-ins |
+| `--ide codex` | `~/.codex/agents/<name>.toml` (`--project` for repo) | generated TOML |
+| `--dest <dir>` | `<dir>/<name>.md` | none |
+
+The Kiro emitter maps `Read`/`Grep`/`Glob`/`Bash` to `read`/`grep`/`glob`/`shell` against [Kiro's built-in tool reference](https://kiro.dev/docs/cli/reference/built-in-tools/), and **names any tool it can't map instead of dropping it silently** — a mistranslated permission is worse than a missing one. It omits `allowedTools` so you're prompted per tool call.
+
+Each generated target omits the permission field it cannot map safely rather than guessing one: Kiro's `allowedTools` and Codex's `sandbox_mode` are both left unset, so an agent inherits the session's permissions and is prompted per call. A widened permission nobody asked for is worse than an extra prompt.
+
+Only **Antigravity** still refuses — its subagents exist solely inside a plugin bundle, which is a container rather than a file drop. Design is worked out in [RFC-0013](docs/rfcs/0013-antigravity-plugin-bundle.md), unimplemented pending demand. [`agents/README.md`](agents/README.md) has the manual route.
 
 ### Third-party catalogs — publish your own skills through the same CLI
 

package/agents/README.md

@@ -40,9 +40,11 @@ Cursor has no subagent file format. Two options:
 
 ### Codex (native subagents)
 
-Codex shipped subagents with GPT-5.5 in April 2026 — `.toml` agent definitions under `.codex/`. That superseded the old advice here, which was to paste the body into a section of `AGENTS.md` because Codex "has no subagent concept."
+```bash
+npx skilldrop-cli install --agent devils-advocate --ide codex   # ~/.codex/agents/<name>.toml
+```
 
-The exact filename and schema were **not confirmed** in the survey, so check Codex's own docs rather than trusting a shape written here. The fallback still works: keep the file at `agents/<name>.md` and open the review turn with "Follow the instructions in `agents/<name>.md` for the diff below."
+Standalone TOML in `~/.codex/agents/` or `.codex/agents/` (`--project`). Codex requires `name`, `description`, and `developer_instructions`, and **rejects unknown fields** — so the emitter writes exactly those three. It leaves `sandbox_mode` unset, which means the agent inherits the parent session's permissions; Codex has no `tools` field, and guessing a sandbox value would either break the agent or silently widen what it can do.
 
 ### Kiro (native custom agents)
 

package/bin/skilldrop.js

@@ -49,9 +49,13 @@ Install/update/uninstall targets (pick one):
                                                 .github/skills (Copilot), Continue / Cline / Aider
 
 Options:
-  --agent            operate on subagents instead of skills. Plain-copy targets only:
-                     Claude Code (~/.claude/agents, --project for repo scope) or --dest.
-                     Copilot/Kiro/Codex need a projection — see agents/README.md.
+  --agent            operate on subagents instead of skills. Targets:
+                       (default)      ~/.claude/agents      Claude Code (--project for repo scope)
+                       --ide kiro     ./.kiro/agents        generated JSON, tools mapped
+                       --ide copilot  ./.github/agents      <name>.agent.md
+                       --ide codex    ~/.codex/agents       generated TOML (--project for repo)
+                       --dest <dir>   any directory         copied as-is
+                     Antigravity needs a plugin bundle (RFC-0013) — see agents/README.md.
   --with-related     also install each skill's related companions (one level)
   --with-hooks       also wire any hooks a skill declares (RFC-0006) — git pre-commit
                      reminders and Claude Code session-start context; degrades where the
@@ -175,11 +179,47 @@ function target(flags) {
   die(`unknown --ide '${ide}' (claude | cursor | kiro; use --dest for anything else)`);
 }
 
+/* Claude Code tool name -> Kiro built-in tool name. Confirmed against
+   kiro.dev/docs/cli/reference/built-in-tools/ — not inferred. Agent configs use these
+   simplified names; Kiro's *hook* matchers use internal names (fs_read, execute_bash)
+   instead, and mixing the two silently grants nothing. */
+const KIRO_TOOLS = {
+  Read: "read", Grep: "grep", Glob: "glob", Bash: "shell",
+  Write: "write", Edit: "write", WebSearch: "web_search", WebFetch: "web_fetch",
+};
+
+function kiroAgentJSON(meta, body) {
+  const declared = meta.tools ? meta.tools.split(",").map((s) => s.trim()).filter(Boolean) : [];
+  const tools = [], unmapped = [];
+  for (const d of declared) (KIRO_TOOLS[d] ? tools : unmapped).push(KIRO_TOOLS[d] || d);
+  // The prompt is inlined rather than a file:// reference: the docs' example is
+  // relative, but whether it resolves against the workspace root or the JSON file is
+  // not stated, and a wrong path fails silently. One self-contained file cannot.
+  const agent = { name: meta.name, description: meta.description, prompt: body, tools };
+  // allowedTools is deliberately omitted — it is auto-approval, so leaving it out means
+  // the user is prompted per tool call. Also sidesteps kirodotdev/Kiro#6714, where
+  // allowedTools does not load as configured.
+  return { json: JSON.stringify(agent, null, 2) + "\n", unmapped: [...new Set(unmapped)] };
+}
+
+/* Codex agent TOML. Schema confirmed at learn.chatgpt.com/docs/agent-configuration/subagents:
+   name, description and developer_instructions are required; unknown fields are rejected.
+   sandbox_mode is deliberately NOT emitted — Codex has no `tools` field, permissions come
+   from sandbox_mode, and its permitted values are unconfirmed. Omitting it inherits the
+   parent session, which is the only behaviour that can neither break the agent nor
+   silently widen what it may do. */
+function codexAgentTOML(meta, body) {
+  const esc = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  const safe = body.includes('"""') ? body.replace(/"""/g, '\\"\\"\\"') : body;
+  return `name = "${esc(meta.name)}"\n` +
+         `description = "${esc(meta.description)}"\n` +
+         `developer_instructions = """\n${safe}\n"""\n`;
+}
+
 /* Only plain-copy targets ship in RFC-0012. Everything else needs a projection the
    install-target model (RFC-0010) has not settled — so say so instead of guessing a path. */
 const AGENT_MANUAL = {
-  copilot: ".github/agents/<name>.agent.md (rename needed)",
-  kiro: ".kiro/agents/<name>.json (JSON wrapper around a file:// prompt)",
+  antigravity: "an agents/ directory inside a plugin bundle you own — see RFC-0013",
   cursor: "a custom mode — Cursor has no agent file format",
 };
 function agentTarget(flags) {
@@ -189,11 +229,42 @@ function agentTarget(flags) {
     return flags.project
       ? { dest: path.resolve(".claude", "agents"), ide }
       : { dest: path.join(os.homedir(), ".claude", "agents"), ide };
+  // Kiro and Copilot agent dirs are repo-relative by convention, so --project is implied.
+  if (ide === "kiro") return { dest: path.resolve(".kiro", "agents"), ide };
+  if (ide === "copilot") return { dest: path.resolve(".github", "agents"), ide };
+  if (ide === "codex")
+    return flags.project
+      ? { dest: path.resolve(".codex", "agents"), ide }
+      : { dest: path.join(os.homedir(), ".codex", "agents"), ide };
   const hint = AGENT_MANUAL[ide];
-  die(`--agent has no plain-copy target for '${ide}'${hint ? ` — it needs ${hint}` : ""}.\n` +
+  die(`--agent has no target for '${ide}'${hint ? ` — it needs ${hint}` : ""}.\n` +
       `       Copy it by hand (see agents/README.md), or use --dest <dir>. Tracked in RFC-0012.`);
 }
 
+/* Write one agent into a target, projecting only where the target's format demands it.
+   Returns the filename written plus any warning worth printing. */
+function writeAgent(cat, a, dest, ide) {
+  const src = agentPath(cat, a);
+  if (ide === "kiro") {
+    const raw = fs.readFileSync(src, "utf8");
+    const body = raw.split("---").slice(2).join("---").trim();
+    const { json, unmapped } = kiroAgentJSON(agentMeta(cat, a), body);
+    fs.writeFileSync(path.join(dest, `${a}.json`), json);
+    return { file: `${a}.json`, warn: unmapped.length
+      ? `  ${a}: no Kiro equivalent for ${unmapped.join(", ")} — dropped from tools, add by hand if needed`
+      : null };
+  }
+  if (ide === "codex") {
+    const raw = fs.readFileSync(src, "utf8");
+    const body = raw.split("---").slice(2).join("---").trim();
+    fs.writeFileSync(path.join(dest, `${a}.toml`), codexAgentTOML(agentMeta(cat, a), body));
+    return { file: `${a}.toml`, warn: null };
+  }
+  const name = ide === "copilot" ? `${a}.agent.md` : `${a}.md`;
+  fs.copyFileSync(src, path.join(dest, name));
+  return { file: name, warn: null };
+}
+
 function ledger(dest) {
   const p = path.join(dest, LEDGER);
   return { path: p, data: fs.existsSync(p) ? readJSON(p) : {} };
@@ -500,14 +571,20 @@ function installAgents(args) {
   const { dest, ide } = agentTarget(args.flags);
   fs.mkdirSync(dest, { recursive: true });
   const l = ledger(dest);
+  const warns = [];
   for (const a of names) {
-    fs.copyFileSync(agentPath(cat, a), path.join(dest, `${a}.md`));
-    l.data[a] = { version: null, source: cat.source }; // agents carry no version yet (RFC-0012)
-    console.log(`installed ${a} -> ${dest}`);
+    const { file, warn } = writeAgent(cat, a, dest, ide);
+    if (warn) warns.push(warn);
+    l.data[a] = { version: null, source: cat.source, file }; // agents carry no version yet (RFC-0012)
+    console.log(`installed ${a} -> ${path.join(dest, file)}`);
   }
   saveLedger(l);
   console.log(`\n${names.length} agent(s) installed (${ide}).`);
+  if (warns.length) console.log(`\nTool mapping:\n${warns.join("\n")}`);
   if (ide === "claude") console.log("Delegate by name, e.g. \"use the devils-advocate agent on this diff\".");
+  if (ide === "kiro") console.log("Kiro grants `tools` but not auto-approval — you are prompted per call by design.");
+  if (ide === "copilot") console.log("Invoke with: copilot --agent <name>");
+  if (ide === "codex") console.log("sandbox_mode is left unset, so each agent inherits the parent session's permissions.");
   if (cat.source !== BUNDLED)
     console.log(`\nWARNING: third-party catalog '${cat.source}'. An agent is a system prompt your tool will adopt — read it before first use. Install copied files only; nothing was executed.`);
 }
@@ -517,7 +594,9 @@ function uninstallAgents(args) {
   const { dest } = agentTarget(args.flags);
   const l = ledger(dest);
   for (const a of args._) {
-    fs.rmSync(path.join(dest, `${a}.md`), { force: true });
+    const rec = l.data[a];
+    for (const f of new Set([rec && rec.file, `${a}.md`, `${a}.json`, `${a}.agent.md`, `${a}.toml`].filter(Boolean)))
+      fs.rmSync(path.join(dest, f), { force: true });
     delete l.data[a];
     console.log(`removed ${a} from ${dest}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Portable AI-agent skills for the deliverables knowledge workers ship \u2014 diagrams, ADRs, PRDs, runbooks, decks, reviews \u2014 installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "bin": {
     "skilldrop": "bin/skilldrop.js"