skilldrop-cli 0.6.0 → 0.7.0

package/README.md

@@ -292,11 +292,14 @@ 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 |
 | `--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.
+
+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

@@ -53,8 +53,9 @@ 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)
                        --dest <dir>   any directory         copied as-is
-                     Codex and Antigravity still refuse with the reason — see agents/README.md.
+                     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
@@ -201,11 +202,24 @@ function kiroAgentJSON(meta, body) {
   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 = {
-  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",
+  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) {
@@ -215,11 +229,13 @@ 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 };
   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 +254,12 @@ function writeAgent(cat, a, dest, ide) {
       ? `  ${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 };
@@ -562,6 +584,7 @@ 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 (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 +595,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.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"