skilldrop-cli 0.6.0 → 0.8.0

package/README.md

@@ -292,11 +292,15 @@ Four targets, each projecting only as much as the tool's format demands:
 | *(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 |
+| `--ide antigravity` | `~/.gemini/config/agents/<name>.md` (`--project` → `.agents/agents/`) | frontmatter rewritten, `subagent: true` added |
 | `--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.
 
-Codex and Antigravity still refuse, printing why: Codex's `.toml` agent schema was never confirmed, and emitting a guess is the one thing worse than not shipping the target. [`agents/README.md`](agents/README.md) has the manual route.
+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.
+
+**Every surveyed tool now installs.** Only Cursor is absent, because it has no agent file format at all — use a custom mode ([`agents/README.md`](agents/README.md) has the steps).
 
 ### Third-party catalogs — publish your own skills through the same CLI
 

package/agents/README.md

@@ -4,7 +4,17 @@ Portable **reviewer agents** — opinionated personas you delegate code and test
 
 The frontmatter makes the file a drop-in **Claude Code subagent**. The body is plain enough to paste into any other tool's agent / mode / system-prompt slot.
 
-Nothing auto-discovers *this* folder at the repo root, so it is the **canonical source of truth** and the table below says where to copy each file. That framing used to be simpler: as of the [July 2026 survey](../docs/designs/ide-primitive-coverage.md), **five tools have a native subagent format** — Claude Code, Kiro, Codex, Copilot, and Antigravity, which registers subagents from a directory literally named `agents/` inside a plugin bundle. The CLI does not install agents into any of them yet ([RFC-0010](../docs/rfcs/0010-install-target-table.md) has to settle the projection model first), so copying by hand remains the route.
+Nothing auto-discovers *this* folder at the repo root, so it is the **canonical source of truth**. As of the [July 2026 survey](../docs/designs/ide-primitive-coverage.md), **five tools have a native subagent format** — Claude Code, Kiro, Codex, Copilot, and Antigravity, which registers subagents from a directory literally named `agents/` inside a plugin bundle.
+
+**The CLI installs into four of them** ([RFC-0012](../docs/rfcs/0012-subagent-installation.md)):
+
+```bash
+npx skilldrop-cli agents                                       # list
+npx skilldrop-cli install --agent devils-advocate              # ~/.claude/agents/
+npx skilldrop-cli install --agent devils-advocate --ide kiro   # .kiro/agents/*.json
+```
+
+**Five of the five tools with a native format now install by command** — Claude Code, Kiro, Codex, Copilot, and Antigravity. Only Cursor needs hand-work, because it has no agent file format at all. Each section below gives the command where one exists, and the manual route either way.
 
 ## The agents
 
@@ -40,34 +50,44 @@ 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)
 
-Kiro reads JSON agent definitions from `.kiro/agents/` (local) or `~/.kiro/agents/` (global). The filename minus `.json` becomes the agent's name.
+```bash
+npx skilldrop-cli install --agent devils-advocate --ide kiro   # .kiro/agents/<name>.json
+```
+
+Kiro reads JSON agent definitions from `.kiro/agents/` (local) or `~/.kiro/agents/` (global). The emitter maps Claude Code tool names to [Kiro's built-ins](https://kiro.dev/docs/cli/reference/built-in-tools/) — `Read`/`Grep`/`Glob`/`Bash` → `read`/`grep`/`glob`/`shell` — and **names any tool it cannot map** rather than dropping it silently.
 
-Its `prompt` field accepts a **`file://` URI**, so the definition can point at the markdown instead of duplicating it — the cleanest projection of any tool surveyed:
+Two choices worth knowing if you hand-write one instead:
 
-```json
-{
-  "name": "devils-advocate",
-  "description": "<paste the description from the agent's frontmatter>",
-  "prompt": "file://./agents/devils-advocate.md",
-  "tools": ["read", "grep", "execute"]
-}
-```
+- **The prompt is inlined, not a `file://` reference.** Kiro's docs show a relative `file://` path but do not say whether it resolves against the workspace root or the JSON file, and a wrong path fails *silently* — the agent loads with no instructions.
+- **`allowedTools` is omitted**, so you are prompted per tool call. That is the right default for a reviewer, and it avoids [kirodotdev/Kiro#6714](https://github.com/kirodotdev/Kiro/issues/6714), where the field does not load as configured.
 
 **Don't use a steering file for this.** Earlier advice here said to drop the agent at `.kiro/steering/<agent>.md`; a steering file with no inclusion mode is loaded into *every* session, which is a permanent context cost for a persona you want on demand. Same reason the CLI stopped writing steering shims for skills.
 
 ### GitHub Copilot (native custom agents)
 
-Copilot reads `.github/agents/<name>.agent.md` (repo) or `~/.copilot/agents/` (personal). The filename minus `.agent.md` is the invocation name — `copilot --agent devils-advocate`. Copy the file in and rename it; the frontmatter needs `name` and `description`, and takes an optional `tools` list.
+```bash
+npx skilldrop-cli install --agent devils-advocate --ide copilot   # .github/agents/<name>.agent.md
+```
+
+Copilot reads `.github/agents/<name>.agent.md` (repo) or `~/.copilot/agents/` (personal). The filename minus `.agent.md` is the invocation name — `copilot --agent devils-advocate`. The install is a pure rename; nothing in the file changes.
 
 ### Antigravity CLI (plugin subagents)
 
-Antigravity registers subagent templates from an `agents/` directory **inside a plugin bundle** at `~/.gemini/antigravity-cli/plugins/<plugin>/agents/`. There is no project-root `agents/` convention, so this is a copy into a bundle you own, not a drop-in.
+```bash
+npx skilldrop-cli install --agent devils-advocate --ide antigravity   # ~/.gemini/config/agents/
+```
+
+Antigravity discovers subagents at `~/.gemini/config/agents/<name>.md` (global) or `.agents/agents/<name>.md` (workspace, `--project`) — markdown with YAML frontmatter, same shape as these files. A plugin bundle is a *third* option, not a requirement; [RFC-0013](../docs/rfcs/0013-antigravity-plugin-bundle.md) records why an earlier draft wrongly thought it was the only one.
+
+The emitter adds **`subagent: true`** — without it the agent exists but `invoke_subagent` cannot reach it — and maps `Read`/`Grep`/`Bash` to `view_file`/`grep_search`/`run_command`. Antigravity has no glob-style tool, so `Glob` is named and dropped rather than bent into `list_dir`.
 
 ### Continue, Cline, Aider, and other tools
 

package/bin/skilldrop.js

@@ -53,8 +53,10 @@ Options:
                        (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)
+                       --ide antigravity  ~/.gemini/config/agents  markdown, subagent: true
                        --dest <dir>   any directory         copied as-is
-                     Codex and Antigravity still refuse with the reason — see agents/README.md.
+                     Cursor has no agent format — use a custom mode (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
@@ -201,11 +203,43 @@ function kiroAgentJSON(meta, body) {
   return { json: JSON.stringify(agent, null, 2) + "\n", unmapped: [...new Set(unmapped)] };
 }
 
+/* Antigravity agent markdown (RFC-0013). Only mappings confirmed in Antigravity's own
+   subagents doc are listed. There is no glob-style tool in its file tooling
+   (view_file / list_dir / grep_search / write_to_file), so Glob is dropped and named
+   rather than bent into list_dir — a different operation. */
+const ANTIGRAVITY_TOOLS = { Read: "view_file", Grep: "grep_search", Bash: "run_command" };
+const ANTIGRAVITY_MODELS = new Set(["inherit", "flash", "pro"]);
+
+function antigravityAgentMD(meta, body) {
+  const declared = meta.tools ? meta.tools.split(",").map((s) => s.trim()).filter(Boolean) : [];
+  const tools = [], unmapped = [];
+  for (const d of declared) (ANTIGRAVITY_TOOLS[d] ? tools : unmapped).push(ANTIGRAVITY_TOOLS[d] || d);
+  // YAML double-quoted scalars are a superset of JSON strings, so JSON.stringify is a
+  // correct quoter here — descriptions contain em-dashes and embedded quotes.
+  const lines = [`name: ${JSON.stringify(meta.name)}`, `description: ${JSON.stringify(meta.description)}`];
+  if (tools.length) lines.push(`tools: [${tools.join(", ")}]`);
+  lines.push("subagent: true"); // required, or invoke_subagent cannot reach it
+  if (ANTIGRAVITY_MODELS.has(meta.model)) lines.push(`model: ${meta.model}`);
+  return { md: `---\n${lines.join("\n")}\n---\n\n${body}\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 = {
-  codex: ".codex/*.toml — the schema was never confirmed, so emitting one would be a guess",
-  antigravity: "an agents/ directory inside a plugin bundle you own",
   cursor: "a custom mode — Cursor has no agent file format",
 };
 function agentTarget(flags) {
@@ -215,11 +249,17 @@ function agentTarget(flags) {
     return flags.project
       ? { dest: path.resolve(".claude", "agents"), ide }
       : { dest: path.join(os.homedir(), ".claude", "agents"), ide };
-  if (ide === "kiro")
-    return flags.project === false
-      ? { dest: path.join(os.homedir(), ".kiro", "agents"), ide }
-      : { dest: path.resolve(".kiro", "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 };
+  if (ide === "antigravity")
+    return flags.project
+      ? { dest: path.resolve(".agents", "agents"), ide }
+      : { dest: path.join(os.homedir(), ".gemini", "config", "agents"), ide };
   const hint = AGENT_MANUAL[ide];
   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.`);
@@ -238,6 +278,21 @@ function writeAgent(cat, a, dest, ide) {
       ? `  ${a}: no Kiro equivalent for ${unmapped.join(", ")} — dropped from tools, add by hand if needed`
       : null };
   }
+  if (ide === "antigravity") {
+    const raw = fs.readFileSync(src, "utf8");
+    const body = raw.split("---").slice(2).join("---").trim();
+    const { md, unmapped } = antigravityAgentMD(agentMeta(cat, a), body);
+    fs.writeFileSync(path.join(dest, `${a}.md`), md);
+    return { file: `${a}.md`, warn: unmapped.length
+      ? `  ${a}: no Antigravity 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 };
@@ -562,6 +617,8 @@ function installAgents(args) {
   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 (ide === "antigravity") console.log("Emitted with `subagent: true` so invoke_subagent can reach them.");
   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.`);
 }
@@ -572,7 +629,7 @@ function uninstallAgents(args) {
   const l = ledger(dest);
   for (const a of args._) {
     const rec = l.data[a];
-    for (const f of new Set([rec && rec.file, `${a}.md`, `${a}.json`, `${a}.agent.md`].filter(Boolean)))
+    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.6.0",
+  "version": "0.8.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"