skilldrop-cli 0.4.1 → 0.6.0

package/README.md

@@ -3,7 +3,9 @@
 [![npm](https://img.shields.io/npm/v/skilldrop-cli)](https://www.npmjs.com/package/skilldrop-cli)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**48 portable AI-agent skills for the deliverables knowledge workers actually ship** — diagrams, design docs, ADRs, PRDs, runbooks, decks, decision logs, threat models, adversarial reviews — installable into **Claude Code**, **Cursor**, **Kiro**, and any AI tool that accepts custom instructions, one skill or one role-based pack at a time:
+**[Browse the catalogue →](https://sananthanarayan.github.io/skilldrop/)** — all 49 skills, filterable by pack, tag, and model tier.
+
+**49 portable AI-agent skills for the deliverables knowledge workers actually ship** — diagrams, design docs, ADRs, PRDs, runbooks, decks, decision logs, threat models, adversarial reviews — installable into **Claude Code**, **Cursor**, **Kiro**, **Codex**, **GitHub Copilot**, and any AI tool that accepts custom instructions, one skill or one role-based pack at a time:
 
 ```bash
 npx skilldrop-cli install --pack product-manager     # or: solution-architect, dev-team,
@@ -252,6 +254,8 @@ npx skilldrop-cli install --pack dev-team --project     # .claude/skills — als
 npx skilldrop-cli install prfaq --ide cursor            # + writes .cursor/rules/prfaq.mdc
 npx skilldrop-cli install --pack sre-oncall --ide kiro  # .kiro/skills — Kiro IDE + Kiro CLI, discovered natively
 npx skilldrop-cli install adr-generator --dest .agents/skills   # Codex + Copilot CLI (see below)
+npx skilldrop-cli agents                                # the reviewer subagents
+npx skilldrop-cli install --agent devils-advocate       # -> ~/.claude/agents/ (RFC-0012)
 npx skilldrop-cli outdated && npx skilldrop-cli update  # skills improve; cp -R never tells you
 npx skilldrop-cli list | skilldrop info <skill> | skilldrop packs | skilldrop uninstall <skill>
 ```
@@ -269,6 +273,31 @@ npx skilldrop-cli install devils-advocate --with-hooks --project
 
 The CLI emits per target and **degrades gracefully** — a `pre-commit-review` hook becomes an IDE-agnostic git hook (needs a git repo); a `session-start` hook becomes a Claude Code `settings.json` entry, and is cleanly skipped where the target has no equivalent (Cursor, Kiro, plain `--dest`), printing what it did and where. Kiro, Codex, and Copilot all have native hook mechanisms the CLI does not emit into yet — see [`docs/designs/ide-primitive-coverage.md`](docs/designs/ide-primitive-coverage.md) for the per-tool survey. Hooks are reminders/context, not autonomous execution — skilldrop skills are agent instructions, so the hook prompts *you* to run the review, it doesn't silently run an AI pass. `skilldrop uninstall` removes any hook artifacts it wrote. Vocabulary and the per-target mapping are in the RFC.
 
+### Reviewer subagents
+
+Two personas you delegate review to, rather than invoke as a skill: [`devils-advocate`](agents/devils-advocate.md) ("will this break?") and [`code-quality`](agents/code-quality.md) ("will the next engineer hate this?"). A subagent runs in its own context with its own tool allowlist — a contract a skill can't express — which is why they live in [`agents/`](agents/) instead of `skills/`.
+
+```bash
+npx skilldrop-cli agents                                    # list them
+npx skilldrop-cli install --agent devils-advocate           # ~/.claude/agents/
+npx skilldrop-cli install --agent code-quality --project    # .claude/agents/, shared with the repo
+```
+
+Then delegate by name: *"use the devils-advocate agent on this diff."*
+
+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 |
+| `--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.
+
 ### Third-party catalogs — publish your own skills through the same CLI
 
 Any git repo or directory shaped like this one is a **catalog**: `skills/<name>/` folders each holding `SKILL.md` + `manifest.json`, optionally a root `packs.json`. That's the whole contract ([RFC-0003](docs/rfcs/0003-third-party-catalogs.md)):

package/agents/README.md

@@ -0,0 +1,84 @@
+# agents
+
+Portable **reviewer agents** — opinionated personas you delegate code and test review to. Each is a single markdown file: Claude Code subagent frontmatter (`name`, `description`, `tools`, `model`) on top, a self-contained system prompt below.
+
+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.
+
+## The agents
+
+| Agent | Reviews for | Question it answers |
+|---|---|---|
+| [`devils-advocate`](devils-advocate.md) | Correctness — edge cases, broken assumptions, staff-engineer pushback, test-coverage gaps | "Will this break?" |
+| [`code-quality`](code-quality.md) | Craft — naming, structure, duplication, needless complexity, readability | "Will the next engineer hate this?" |
+
+They are deliberately **split, not merged.** A single "review my code" agent dilutes both jobs — bug-hunting and craft pull in different directions. Run them as two passes. `devils-advocate` here is the subagent form of the [`devils-advocate` skill](../skills/devils-advocate/SKILL.md); same persona, packaged for a tool's native agent slot instead of on-demand skill invocation.
+
+## Installing an agent into your tool
+
+### Claude Code (native subagents)
+
+Claude Code reads subagents from `.claude/agents/`. Copy the file in as-is — the frontmatter is already correct:
+
+```bash
+# project-scope (shared with the team via the repo)
+mkdir -p .claude/agents && cp agents/devils-advocate.md .claude/agents/
+
+# user-scope (every project on your machine)
+mkdir -p ~/.claude/agents && cp agents/code-quality.md ~/.claude/agents/
+```
+
+Then delegate by name — "use the devils-advocate agent on this diff" — or let Claude Code auto-route based on the `description`. Each subagent runs in its own context window.
+
+### Cursor (custom modes / rules)
+
+Cursor has no subagent file format. Two options:
+
+- **Custom mode** (cleanest): Settings → Chat → Custom Modes → New. Paste the agent's **body** (everything below the frontmatter) as the mode's instructions; use the `description` as the mode name.
+- **Project rule**: create `.cursor/rules/<agent>.mdc`, paste the body under a frontmatter block (`description:` from the agent file, `alwaysApply: false`). Invoke by attaching it with `@` or describing the review task.
+
+### 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."
+
+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."
+
+### 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.
+
+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:
+
+```json
+{
+  "name": "devils-advocate",
+  "description": "<paste the description from the agent's frontmatter>",
+  "prompt": "file://./agents/devils-advocate.md",
+  "tools": ["read", "grep", "execute"]
+}
+```
+
+**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.
+
+### 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.
+
+### Continue, Cline, Aider, and other tools
+
+No standard agent directory. Two patterns work everywhere:
+
+- **Context attachment** — keep the file in the repo and attach it to the review turn (Continue/Cline `@file`, Aider `/add agents/<agent>.md`), then tell the tool to follow it.
+- **Custom prompt** — paste the agent body into the tool's custom-prompt / system-prompt config. The `description` field is a good seed for the agent's name.
+
+## Adding a new agent
+
+1. Create `agents/<name>.md` with the frontmatter shape above (`name` = filename, use-case-first `description` ending in trigger phrases, read-only `tools` for a reviewer).
+2. Write the body as a self-contained system prompt: who the agent is, what it reviews, how it reports (severity tags + `file:line` + concrete fix), and what it explicitly does *not* do.
+3. Match the repo voice — opinionated, concrete, `✅`/`❌` and `🟥`/`🟧`/`🟨`/`⚪` used semantically (see [AGENTS.md](../AGENTS.md)).
+4. Add a row to **The agents** table above.

package/agents/code-quality.md

@@ -0,0 +1,40 @@
+---
+name: code-quality
+description: Craft-and-maintainability reviewer of just-written code. Finds what the next engineer will hate — bad names, tangled structure, duplication, needless complexity, leaky abstractions, dead code, and unreadable control flow. Does NOT hunt for bugs (that's the devils-advocate agent). Delegate to it when code works but you want it to read well before it ships.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are a senior engineer reviewing for craft, not correctness. The code under review works — you assume the tests pass and the logic is sound. Your job is the question the author can't ask about their own code: **will the engineer who touches this in six months understand it fast, or curse the author?**
+
+You review **the change, not the repo.** Scope is the just-written diff or the files the user points at. Never restyle the whole codebase.
+
+## What you review
+
+Run the change through five lenses. Skip lenses that don't apply.
+
+1. **Naming.** Names that lie, abbreviate without need, or carry no information (`data`, `tmp`, `handle`, `doStuff`). A good name makes a comment unnecessary. Propose the better name.
+2. **Structure & cohesion.** Functions doing five things, classes with split responsibility, modules importing across boundaries they shouldn't, logic that belongs one layer up or down. Point at the seam where it should split.
+3. **Duplication.** Copy-pasted blocks, parallel structures that drift, the third occurrence of a pattern that wants extracting. Name all copies by `file:line`.
+4. **Needless complexity.** Cleverness over clarity, premature abstraction, deep nesting that a guard clause flattens, a config flag nobody uses, a layer that only forwards. Simpler is the goal — show the simpler form.
+5. **Readability & dead weight.** Control flow you have to trace twice, comments that restate the code instead of explaining why, commented-out code, unreachable branches, unused params/imports/exports.
+
+## How you report
+
+- Lead with a one-line read: is this clean, acceptable, or in need of work before it ships?
+- Then findings, each tagged by severity:
+  - 🟧 **major** — actively misleading or will compound into a maintenance problem (a lying name, a god function, the same logic in three places).
+  - 🟨 **minor** — friction the next reader pays for (awkward structure, a comment that should be a name, avoidable nesting).
+  - ⚪ **nit** — polish. Optional, batch these.
+- Every finding has: `file:line`, what's wrong in one sentence, and the concrete improvement — show the better name, the extracted function signature, or the flattened control flow. Don't just say "this is complex."
+- End with **"what reads well"** — the parts that are clean, so the author keeps them.
+
+## Rules
+
+- ✅ Show, don't lecture. ❌ "This function is too long" → ✅ "`syncOrders()` at sync.go:88 does fetch + transform + persist + notify. Split `notify` out — it's the only part with external side effects and it makes the rest unit-testable."
+- ✅ Respect the surrounding style. Match the file's existing idiom, naming convention, and comment density — don't impose your taste over a consistent house style.
+- ❌ Don't flag correctness, security, or test gaps — that's the **devils-advocate** agent's job. If you spot a real bug while reviewing, note it in one line and hand it off; don't review it here.
+- ❌ Don't propose a rewrite when a rename or an extracted function fixes it. The smallest change that removes the friction wins.
+- ❌ Don't invent findings to hit a count. "This reads well, no major findings" is a valid and useful result.
+
+This is the craft reviewer. For "will it break?" — bugs, edge cases, broken assumptions, missing tests — delegate to the **devils-advocate** agent instead.

package/agents/devils-advocate.md

@@ -0,0 +1,40 @@
+---
+name: devils-advocate
+description: Adversarial reviewer of just-written code and tests. Hunts for what will break — edge cases the first pass missed, assumptions that won't survive future requirements, what a staff engineer would push back on in review, and test-coverage gaps. Delegate to it right after a feature is declared "done", before opening a PR or merging.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are a senior engineer in code review whose only job is to find what the implementation missed. Code that "works on the happy path" is the default state of just-written code — your job is to break that assumption.
+
+You review **the change, not the repo.** Scope is the just-written diff, the files the user points at, or `git diff` of the working tree. Never sweep the whole codebase.
+
+## What you challenge
+
+Run the change through four lenses. Skip lenses that don't apply; don't pad.
+
+1. **Edge cases the first pass missed.** Empty input, nulls, zero, negative, max-size, Unicode, concurrent callers, partial failure, retries, timeouts. For each: state the input, the current behavior, and what it should do.
+2. **Assumptions that won't survive 6 months.** Hard-coded limits, single-region/single-tenant baked in, ordering assumed, "this list is always small", schema that can't evolve. Name the assumption and the future requirement that breaks it.
+3. **What a staff engineer pushes back on.** Concurrency and race conditions, error handling and error mapping, security (authz, injection, secrets, SSRF), observability (can you debug this at 3am?), blast radius, idempotency, resource leaks.
+4. **Test-coverage gaps.** Which new code paths have no test? Which tests assert the happy path only? Which tests would still pass if the code were subtly wrong (assertion theater)? Name the missing test case concretely.
+
+## How you report
+
+- Lead with a one-line verdict: is this safe to merge or not?
+- Then findings, each tagged by severity:
+  - 🟥 **blocker** — will cause incorrect behavior, data loss, or a security hole. Do not merge.
+  - 🟧 **major** — real bug or gap under realistic conditions. Fix before merge.
+  - 🟨 **minor** — works but fragile or surprising. Fix soon.
+  - ⚪ **nit** — style/polish. Optional.
+- Every finding has: `file:line` evidence, a one-sentence reproducible scenario, and a concrete fix or the exact missing test case.
+- End with a short **"what's solid"** section — what the implementation got right, so the author knows what not to touch.
+
+## Rules
+
+- ✅ Be concrete. ❌ "Consider adding more validation" → ✅ "`parseDate()` at handler.go:42 throws on empty string; the API contract allows an empty `since` param. Add a guard returning the default window."
+- ✅ Default to suspicion. If you can't tell whether a path is handled, say so and tell the author what to check.
+- ❌ Don't invent findings to hit a count. Zero blockers is a valid result — say so.
+- ❌ Don't rewrite the whole thing. You point; the author fixes.
+- ❌ Not a substitute for human review — this is a pre-pass that catches the obvious-in-hindsight before a human spends their attention.
+
+This is the bug-and-gap reviewer. For craft and maintainability (naming, structure, duplication, readability) delegate to the **code-quality** agent instead — keep the two reviews separate so neither dilutes the other.

package/bin/skilldrop.js

@@ -24,12 +24,15 @@ Usage:
   skilldrop list [--from <src>]           all skills in a catalog (name, version, tier)
   skilldrop info <skill> [--from <src>]   description, related, packs, deps
   skilldrop packs [--from <src>]          role-based packs
+  skilldrop agents [--from <src>]         reviewer subagents in a catalog
   skilldrop install <skill...>            install skills (default: Claude Code, user scope)
   skilldrop install --pack <name>         install a whole pack
   skilldrop install --all                 install every skill in the catalog
+  skilldrop install --agent <name...>     install reviewer subagents (RFC-0012)
   skilldrop update                        re-copy installed skills whose version changed
   skilldrop outdated                      show installed vs current versions, change nothing
   skilldrop uninstall <skill...>          remove skills (and wiring files this tool wrote)
+  skilldrop uninstall --agent <name...>   remove subagents
   skilldrop validate [--from <src>]       structural check of a catalog (for catalog authors)
 
 Catalogs:
@@ -46,6 +49,12 @@ Install/update/uninstall targets (pick one):
                                                 .github/skills (Copilot), Continue / Cline / Aider
 
 Options:
+  --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
+                       --dest <dir>   any directory         copied as-is
+                     Codex and Antigravity still refuse with the reason — 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
@@ -93,6 +102,30 @@ function skillsIn(cat) {
   return fs.readdirSync(cat.skillsDir).filter((d) => fs.statSync(path.join(cat.skillsDir, d)).isDirectory()).sort();
 }
 function manifestOf(cat, s) { return readJSON(path.join(cat.skillsDir, s, "manifest.json")); }
+
+/* Agents (RFC-0012): single markdown files, frontmatter is already Claude Code's format.
+   Optional in a catalog — a third-party catalog with no agents/ is still valid. */
+function agentsIn(cat) {
+  const d = path.join(cat.dir, "agents");
+  if (!fs.existsSync(d)) return [];
+  return fs.readdirSync(d).filter((f) => f.endsWith(".md") && f !== "README.md").map((f) => f.slice(0, -3)).sort();
+}
+function agentPath(cat, a) { return path.join(cat.dir, "agents", `${a}.md`); }
+function agentMeta(cat, a) {
+  const fm = (fs.readFileSync(agentPath(cat, a), "utf8").split("---")[1] || "");
+  const get = (k) => { const m = fm.match(new RegExp("^" + k + ":\\s*(.+)$", "m")); return m ? m[1].trim() : ""; };
+  return { name: get("name"), description: get("description"), tools: get("tools"), model: get("model") };
+}
+
+/* Same gate the skills get, applied to agents before anything is copied. */
+function checkAgent(cat, a) {
+  const problems = [];
+  if (!fs.existsSync(agentPath(cat, a))) return [`agents/${a}.md missing`];
+  const m = agentMeta(cat, a);
+  if (m.name !== a) problems.push(`frontmatter name '${m.name}' != filename '${a}'`);
+  if (!m.description) problems.push("frontmatter missing description");
+  return problems;
+}
 function packsOf(cat) {
   const p = path.join(cat.dir, "packs.json");
   return fs.existsSync(p) ? readJSON(p).packs : null;
@@ -145,6 +178,71 @@ 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)] };
+}
+
+/* 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) {
+  if (flags.dest) return { dest: path.resolve(flags.dest), ide: "generic" };
+  const ide = flags.ide || "claude";
+  if (ide === "claude")
+    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 };
+  if (ide === "copilot") return { dest: path.resolve(".github", "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.`);
+}
+
+/* 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 };
+  }
+  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) : {} };
@@ -317,6 +415,7 @@ function copyOne(cat, s, dest, ide, l, notes) {
 }
 
 function install(args) {
+  if (args.flags.agent) return installAgents(args);
   const cat = resolveCatalog(args.flags.from);
   let names = expandNames(args, cat);
   if (args.flags["with-related"]) {
@@ -404,6 +503,7 @@ function outdated(args) {
 }
 
 function uninstall(args) {
+  if (args.flags.agent) return uninstallAgents(args);
   if (!args._.length) die("pass skill names to uninstall");
   const { dest, ide } = target(args.flags);
   const l = ledger(dest);
@@ -418,6 +518,68 @@ function uninstall(args) {
   saveLedger(l);
 }
 
+function listAgents(args) {
+  const cat = resolveCatalog(args.flags.from);
+  const names = agentsIn(cat);
+  if (!names.length) return console.log(`catalog '${cat.source}' ships no agents.`);
+  const w = Math.max(...names.map((n) => n.length));
+  for (const a of names) {
+    const m = agentMeta(cat, a);
+    console.log(`${a.padEnd(w)}  ${m.description}`);
+  }
+  console.log(`\n${names.length} agent(s). Install one: skilldrop install --agent <name>`);
+}
+
+function installAgents(args) {
+  const cat = resolveCatalog(args.flags.from);
+  const available = agentsIn(cat);
+  if (!available.length) die(`catalog '${cat.source}' ships no agents`);
+  const names = args._.length ? args._.slice() : (args.flags.all ? available : []);
+  if (!names.length) die("nothing to install — pass agent names, or --all");
+  for (const a of names) if (!available.includes(a)) die(`unknown agent '${a}' in catalog '${cat.source}'`);
+
+  let bad = 0;
+  for (const a of names) {
+    const problems = checkAgent(cat, a);
+    for (const pr of problems) console.error(`refused ${a}: ${pr}`);
+    if (problems.length) bad++;
+  }
+  if (bad) die(`${bad} agent(s) failed the structural check — nothing was installed`);
+
+  const { dest, ide } = agentTarget(args.flags);
+  fs.mkdirSync(dest, { recursive: true });
+  const l = ledger(dest);
+  const warns = [];
+  for (const a of names) {
+    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 (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.`);
+}
+
+function uninstallAgents(args) {
+  if (!args._.length) die("pass agent names to uninstall");
+  const { dest } = agentTarget(args.flags);
+  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)))
+      fs.rmSync(path.join(dest, f), { force: true });
+    delete l.data[a];
+    console.log(`removed ${a} from ${dest}`);
+  }
+  saveLedger(l);
+}
+
 function list(args) {
   const cat = resolveCatalog(args.flags.from);
   const rows = skillsIn(cat).map((s) => {
@@ -475,7 +637,7 @@ function validateCmd(args) {
 
 const args = parseArgs(process.argv.slice(2));
 const cmd = args._.shift();
-const commands = { list, info, packs: listPacks, install, update, outdated, uninstall, validate: validateCmd };
+const commands = { list, info, packs: listPacks, agents: listAgents, install, update, outdated, uninstall, validate: validateCmd };
 if (!cmd || cmd === "help" || args.flags.help) console.log(HELP);
 else if (commands[cmd]) commands[cmd](args);
 else die(`unknown command '${cmd}' — run: skilldrop help`);

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.4.1",
-  "description": "Portable AI-agent skills for the deliverables knowledge workers ship — diagrams, ADRs, PRDs, runbooks, decks, reviews — installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
+  "version": "0.6.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"
   },
   "files": [
     "bin/",
     "skills/",
+    "agents/",
     "packs.json",
     "model-routing.json"
   ],

package/skills/deck-builder/manifest.json

@@ -5,7 +5,7 @@
   "entrypoint": "SKILL.md",
   "deps": {
     "npm": [],
-    "pip": ["python-pptx>=0.6.21"]
+    "pip": ["python-pptx==1.0.2"]
   },
   "env": { "required": [], "optional": [] },
   "related": ["audience-profile", "slide-outliner"],

package/skills/deck-builder/requirements.txt

@@ -1 +1,3 @@
-python-pptx>=0.6.21
+# Pinned, not ranged: an open range lets a future release install itself unreviewed.
+# python-pptx 1.0.2 requires Python >= 3.8.
+python-pptx==1.0.2

package/skills/figma-diagrams/SKILL.md

@@ -55,7 +55,8 @@ If `FIGMA_TOKEN` is not set, tell the user how to set it before running the scri
    cd path/to/figma-diagrams && python3 scripts/inspect_file.py <FILE_KEY>
    ```
 
-   Dependencies (just `requests`) are declared in `manifest.json` and `requirements.txt`. Install once with:
+   Dependencies (just `requests`, pinned) are declared in `manifest.json` and `requirements.txt`.
+   **Requires Python 3.10+** — the pinned `requests` drops older interpreters. Install once with:
 
    ```bash
    python3 -m pip install -r requirements.txt

package/skills/figma-diagrams/manifest.json

@@ -6,7 +6,7 @@
   "deps": {
     "npm": [],
     "pip": [
-      "requests>=2.28"
+      "requests==2.34.2"
     ]
   },
   "env": {

package/skills/figma-diagrams/requirements.txt

@@ -1 +1,3 @@
-requests>=2.28
+# Pinned, not ranged: an open range lets a future release install itself unreviewed.
+# requests 2.34.2 requires Python >= 3.10.
+requests==2.34.2