skilldrop-cli 0.11.7 → 0.11.9

package/README.md

@@ -424,6 +424,9 @@ 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 loops                                 # the five loops, their stages and gates
+npx skilldrop-cli install --loop build                  # a loop + every stage skill it sequences (RFC-0028)
+npx skilldrop-cli install --loop --pack sre-oncall      # every loop that pack declares
 npx skilldrop-cli agents                                # the reviewer subagents
 npx skilldrop-cli install --agent devils-advocate       # -> ~/.claude/agents/ (RFC-0012)
 npx skilldrop-cli install --panel review                # the whole review fleet: 3 subagents + the pre-merge-review orchestrator (RFC-0020)
@@ -432,7 +435,7 @@ npx skilldrop-cli list | skilldrop info <skill> | skilldrop packs | skilldrop un
 npx skilldrop-cli list --json                            # machine-readable: list/info/packs/agents/outdated (RFC-0021)
 ```
 
-`--with-related` also pulls each skill's companions. From a clone (or before the package is published): `node bin/skilldrop.js <same args>`. Scope and design: [RFC-0002](docs/rfcs/0002-skilldrop-cli.md), full command surface in [`docs/designs/skilldrop-cli-design.md`](docs/designs/skilldrop-cli-design.md).
+`--loop` installs a loop as an invokable skill (its `LOOP.md` is already `SKILL.md`-shaped) plus the skills its stages name — add `--no-skills` for the loop alone, which still runs because each stage degrades through its declared `fallback`. `--with-related` also pulls each skill's companions. From a clone (or before the package is published): `node bin/skilldrop.js <same args>`. Scope and design: [RFC-0002](docs/rfcs/0002-skilldrop-cli.md), full command surface in [`docs/designs/skilldrop-cli-design.md`](docs/designs/skilldrop-cli-design.md).
 
 ### Or: the Claude Code plugin marketplace
 
@@ -460,16 +463,18 @@ The six **pack plugins** work differently, because a plugin's skills have to sit
 
 `.claude-plugin/{marketplace,plugin}.json` are generated from `package.json` + `packs.json` by [`build_marketplace.py`](build_marketplace.py) (`--check` guards drift in CI; `--dist` renders the branch). Use the CLI above when you want per-skill granularity, another IDE, or hooks; use the marketplace when you're in Claude Code. Rationale: [RFC-0027](docs/rfcs/0027-retire-agentbundle-export.md).
 
-### Hooks (opt-in) — wire a skill to an event
+### Everything else about installing
 
-Some loop-shaped skills declare **hooks** — event-triggered nudges the CLI wires into your environment when you pass `--with-hooks` ([RFC-0006](docs/rfcs/0006-per-ide-hooks.md)). It's off by default, so a plain install never touches your git repo or editor settings.
+The long-form install material moved to [`guides/`](guides/) so this page stays scannable:
 
-```bash
-npx skilldrop-cli install devils-advocate --with-hooks --project
-# → appends a marker-fenced reminder to .git/hooks/pre-commit: "run /devils-advocate on staged changes"
-```
-
-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.
+| If you want to | Read |
+|---|---|
+| Install by hand into a specific IDE | [Install a skill into your IDE](guides/how-to/install-per-ide.md) |
+| Wire a skill to an event (opt-in hooks) | [Wire a skill to an event](guides/how-to/wire-a-hook.md) |
+| Publish your own catalogue for `--from` | [Publish your own catalogue](guides/how-to/publish-a-catalogue.md) |
+| Use the two skills that ship scripts | [Skills that ship scripts](guides/reference/skills-with-scripts.md) |
+| Add a skill or a loop to this repo | [Author a skill](guides/how-to/author-a-skill.md) · [Author a loop](guides/how-to/author-a-loop.md) |
+| Understand why it is built this way | [Why loops](guides/explanation/loops.md) · [ARCHITECTURE.md](ARCHITECTURE.md) |
 
 ### Reviewer subagents
 
@@ -500,145 +505,6 @@ Each generated target omits the permission field it cannot map safely rather tha
 
 **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
-
-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)):
-
-```bash
-npx skilldrop-cli list --from https://github.com/you/your-skills
-npx skilldrop-cli install my-skill --from https://github.com/you/your-skills#v1.2   # #ref pins a branch/tag
-npx skilldrop-cli install --pack starter --from ../local-catalog
-npx skilldrop-cli update      # updates bundled and third-party skills side by side — the ledger remembers each skill's source
-```
-
-The CLI also reads **agentbundle-shaped catalogs** ([agent-ready-repo](https://github.com/eugenelim/agent-ready-repo)) — `packs/<pack>/.apm/skills/<name>/SKILL.md` with a `pack.toml` per pack — so you can install *its* packs through the same command ([RFC-0014](docs/rfcs/0014-agentbundle-interop.md)). This is one-directional by design: skilldrop reads his shape, and no longer publishes a generated catalogue back into it ([RFC-0027](docs/rfcs/0027-retire-agentbundle-export.md)). Both shapes share the agentskills.io `SKILL.md`, so the reader just maps his packs onto the accessors above:
-
-```bash
-npx skilldrop-cli packs --from https://github.com/eugenelim/agent-ready-repo
-npx skilldrop-cli install --pack contracts --from https://github.com/eugenelim/agent-ready-repo --dest .agents/skills
-```
-
-Safety model: installs **copy files only — nothing from a catalog is ever executed**; every skill passes a structural check before copying (broken folders are refused with reasons); and third-party installs print a review-before-use warning, because skills are instructions your AI agent will follow — read a stranger's `SKILL.md` before letting your agent obey it.
-
-**Authoring a catalog:** mirror the layout above, then check it with `npx skilldrop-cli validate --from <your-repo-or-path>` before publishing. `related`, `packs.json`, and `requirements.txt` all work in third-party catalogs exactly as they do here.
-
-### Manual install
-
-Each skill is a plain directory. Installation is always the same two steps: (1) copy the skill folder into your IDE's skills/rules location, then (2) install the skill's dependencies (the commands are in `manifest.json` under `deps`, or run the install line from the skill's SKILL.md). Optionally, also copy the companions listed under `related` in the skill's `manifest.json` — skills reference each other, and while a hand-off to an uninstalled sibling degrades gracefully to inline guidance, the pipelines work best complete.
-
-### Claude Code
-
-Claude Code reads skills from two locations:
-
-- **User-scope** (available in every project): `~/.claude/skills/<skill-name>/`
-- **Project-scope** (tracked with the repo): `<project>/.claude/skills/<skill-name>/`
-
-Install a skill by copying its folder — drop the directory directly into the skills location, **not** its parent category folder:
-
-```bash
-# user-scope (recommended for personal use)
-mkdir -p ~/.claude/skills
-cp -R skills/architecture-diagrams ~/.claude/skills/
-cp -R skills/figma-diagrams ~/.claude/skills/
-
-# project-scope (recommended when sharing with a team)
-mkdir -p .claude/skills
-cp -R skills/architecture-diagrams .claude/skills/
-cp -R skills/figma-diagrams .claude/skills/
-```
-
-Claude Code discovers the skill via its `SKILL.md` frontmatter `name` field. Invoke it in chat with `/<skill-name>` or by describing the task — Claude will route to the matching skill automatically.
-
-### Cursor
-
-Cursor does not have a native "skills" concept, but you can install a skill as a **project rule**:
-
-1. Copy the skill folder somewhere in the repo (e.g. `.cursor/skills/<skill-name>/`):
-   ```bash
-   mkdir -p .cursor/skills
-   cp -R skills/architecture-diagrams .cursor/skills/
-   ```
-
-2. Create `.cursor/rules/<skill-name>.mdc` that points Cursor at it:
-   ```markdown
-   ---
-   description: <paste the skill's description from manifest.json>
-   globs:
-   alwaysApply: false
-   ---
-   Follow the instructions in .cursor/skills/<skill-name>/SKILL.md when the user requests this task.
-   ```
-
-3. In chat, attach `SKILL.md` with `@` or simply describe the task — the rule will fire when the description matches.
-
-### Kiro (IDE and CLI)
-
-Kiro has native **Agent Skills**, and Kiro IDE and Kiro CLI read the same directories. Copy the folder in — that's the whole install:
-
-```bash
-mkdir -p .kiro/skills                  # workspace scope
-cp -R skills/figma-diagrams .kiro/skills/
-
-mkdir -p ~/.kiro/skills                # global scope, every project
-cp -R skills/figma-diagrams ~/.kiro/skills/
-```
-
-Kiro matches the skill by its `SKILL.md` frontmatter `name` (which must equal the folder name) and `description` — the same contract every other tool uses.
-
-**No steering file needed.** Earlier versions of the CLI also wrote `.kiro/steering/<skill-name>.md` pointing back at the skill. That predates native Agent Skills, and because a steering file without frontmatter is *always* loaded, it pinned one description per installed skill into every session's context — to point at a folder Kiro already reads. The CLI no longer writes them, and `install`/`uninstall` remove any it wrote before. A steering file it didn't author is left alone, with a note.
-
-### Codex and GitHub Copilot
-
-Both read `SKILL.md` folders, and both deliberately read *other* tools' directories — so a skilldrop install often already works with no extra step:
-
-| Path | Read by |
-|---|---|
-| `.claude/skills/` | Claude Code, **Copilot CLI** |
-| `.agents/skills/` | **Codex** (project), **Copilot CLI** |
-| `.github/skills/` | **Copilot** |
-| `~/.codex/skills/` | Codex (personal) |
-| `~/.copilot/skills/` | Copilot (personal) |
-
-**If you already ran `skilldrop install --project`, Copilot CLI can use every skill you installed** — `.claude/skills/` is one of its discovery paths. Otherwise pick the path your tool reads:
-
-```bash
-npx skilldrop-cli install --pack dev-team --dest .agents/skills    # Codex + Copilot CLI
-npx skilldrop-cli install --pack dev-team --dest .github/skills    # Copilot
-npx skilldrop-cli install --pack dev-team --dest ~/.codex/skills   # Codex, all projects
-```
-
-There is no `--ide codex` or `--ide copilot` flag yet, and `--dest` is not a workaround here — it writes the identical folder the native flags would. Both tools also read a repo-root `AGENTS.md`, which this repo has.
-
-### Continue, Cline, Aider, and other agents
-
-These tools don't have a standard skills directory yet. Two patterns work:
-
-- **Context attachment.** Copy the skill folder anywhere in the repo, then attach `SKILL.md` to your prompt (Continue: `@file`, Cline: `@file`, Aider: `/add <path>`) and tell the agent to follow it.
-- **Custom prompt / agent.** Paste `SKILL.md` into the IDE's custom-agent or system-prompt configuration. The skill's `manifest.json` `description` field is a good seed for the agent's name/summary.
-
-In all cases, the scripts are invoked from the **copied** folder, so keep the directory structure intact — don't flatten `scripts/` or `templates/` out of the skill folder.
-
-### VS Code (Continue / Cline extensions)
-
-These behave like the "Other agents" path above. For Continue, you can also add the skill folder to `.continue/config.json` under `contextProviders` so `SKILL.md` shows up in `@` suggestions.
-
-## Installing dependencies
-
-Each skill declares its deps in `manifest.json`:
-
-- **`deps.npm`** → run `npm install <packages>` before using the skill (or let `SKILL.md` step 1 install them on demand).
-- **`deps.pip`** → run `python3 -m pip install -r <skill>/requirements.txt`.
-
-Per-skill quick reference:
-
-| Skill | Install command (run from inside the copied skill folder) |
-|---|---|
-| `figma-diagrams` | `python3 -m pip install -r requirements.txt` + `export FIGMA_TOKEN=figd_...` |
-| `deck-builder` | `python3 -m pip install -r requirements.txt` (installs `python-pptx`) |
-| _all other skills_ | _no runtime deps — pure markdown skills_ |
-
-For `figma-diagrams`, you also need a [Figma Personal Access Token](https://www.figma.com/developers/api#access-tokens) exported as the `FIGMA_TOKEN` env var.
-
 ## Reviewer agents
 
 The [`agents/`](agents/) folder ships **portable reviewer personas** — single-file agents you delegate code and test review to, packaged in Claude Code subagent format (frontmatter + system prompt) but written so the body pastes into Cursor, Codex, Kiro, Continue, Cline, or Aider just as cleanly.
@@ -647,65 +513,10 @@ The [`agents/`](agents/) folder ships **portable reviewer personas** — single-
 |---|---|---|
 | [`devils-advocate`](agents/devils-advocate.md) | Correctness — edge cases, broken assumptions, staff-engineer pushback, test gaps | "Will this break?" |
 | [`code-quality`](agents/code-quality.md) | Craft — naming, structure, duplication, complexity, readability | "Will the next engineer hate this?" |
-
 | [`security-reviewer`](agents/security-reviewer.md) | Exploitability — injection, authz gaps, secret handling, unsafe deserialisation | "How would someone abuse this?" |
 
 No tool auto-discovers a folder named `agents/`; it's the canonical source of truth. See [`agents/README.md`](agents/README.md) for where to copy each file in your tool — `.claude/agents/` for Claude Code, a custom mode for Cursor, an `AGENTS.md` section for Codex, a steering file or custom agent for Kiro.
 
-## Skill Usage
-
-All skills are invoked in chat. Arguments are passed as plain text after the skill's trigger phrase (or via `$ARGUMENTS` when invoked as a slash command in Claude Code).
-
-### `architecture-diagrams`
-
-Natural-language trigger (works in any IDE that has the skill installed):
-
-> Draw me a Mermaid diagram of a three-tier web app on AWS with an ALB, two ECS services, and an RDS Postgres backend.
-
-Slash-command form (Claude Code):
-
-```
-/architecture-diagrams three-tier web app on AWS with ALB, two ECS services, RDS Postgres
-```
-
-Everything after the slash command becomes `$ARGUMENTS` inside the skill.
-
-### `figma-diagrams`
-
-Natural-language trigger:
-
-> Inspect the structure of this Figma file: https://figma.com/file/abc123/MyArchitecture
-
-Slash-command form (Claude Code):
-
-```
-/figma-diagrams inspect https://figma.com/file/abc123/MyArchitecture
-/figma-diagrams post-comment https://figma.com/file/abc123/MyArchitecture "Looks good — ship it."
-```
-
-The skill parses `$ARGUMENTS` to figure out which Figma URL you mean and which action to take.
-
-## Adding a new skill
-
-Full contributor guide — the three lanes, the PR gates, and the release flow — is in [CONTRIBUTING.md](CONTRIBUTING.md). The short version:
-
-0. Write a one-page RFC first — copy [`docs/rfcs/0000-template.md`](docs/rfcs/0000-template.md) to `docs/rfcs/NNNN-<slug>.md` and record the problem, the fit check, and the alternatives. New skills and structural changes need one; fixes to existing skills don't.
-1. Create `skills/<your-skill>/SKILL.md` with this frontmatter:
-   ```yaml
-   ---
-   name: your-skill
-   description: One sentence, use-case-first. AI agents match this against user prompts to decide when to invoke.
-   ---
-   ```
-2. Add `skills/<your-skill>/manifest.json` with the same `name` + `description` plus declared `deps` and required env vars — this is what makes the skill portable across IDEs.
-3. Keep `SKILL.md` short (under ~500 lines). Move long reference material into sibling files like `reference.md`, `examples.md`, or `templates/`.
-4. If your skill needs scripts, drop them in `scripts/` and reference them with a path relative to the skill folder — **avoid hard-coding `${CLAUDE_SKILL_DIR}` only**; show both paths so non–Claude-Code users aren't stuck.
-5. Add an `evals/` folder: `evals.json` (at least one realistic prompt with a list of assertions the output must satisfy) and `eval_queries.json` (phrases that should and should **not** trigger the skill). These double as the checklist for the manual test pass and keep the `description` honest about when the skill fires.
-6. Add an entry to the **Skills in this repo** table above and to the **Installing dependencies** table.
-7. Add the skill to at least one pack **and** at least one outcome in `packs.json`.
-8. If the change is going out in a release, add a bullet to [`CHANGELOG.md`](CHANGELOG.md) under the new version — the site build fails without one.
-9. Run `python3 validate.py` from the repo root — it checks name consistency, the tier sync with `model-routing.json`, the `related`↔SKILL.md reference sync, description sync, pack and outcome membership, and eval file shape.
-
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/bin/skilldrop.js

@@ -37,16 +37,20 @@ Usage:
   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 loops [--from <src>]          loops — sequenced stages over skills (RFC-0028)
   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 install --loop <name...>      install loops + the stage skills they sequence
+                                          (--no-skills for the loop alone) (RFC-0028)
   skilldrop install --panel review        install the review panel — the 3 reviewer subagents +
                                           the pre-merge-review orchestrator that fires them (RFC-0020)
   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 uninstall --loop <name...>    remove loops (stage skills are left in place)
   skilldrop validate [--from <src>]       structural check of a catalog (for catalog authors)
   skilldrop scan [<skill...>] [--from <src>]  supply-chain scan — flag network/exec/credential
                                           patterns in scripts and injection-shaped instructions
@@ -740,6 +744,7 @@ function installPanel(args) {
 
 function install(args) {
   if (args.flags.panel) return installPanel(args);
+  if (args.flags.loop) return installLoops(args);
   if (args.flags.agent) return installAgents(args);
   const cat = resolveCatalog(args.flags.from);
   let names = expandNames(args, cat);
@@ -846,6 +851,7 @@ function outdated(args) {
 
 function uninstall(args) {
   if (args.flags.agent) return uninstallAgents(args);
+  if (args.flags.loop) return uninstallLoops(args);
   if (!args._.length) die("pass skill names to uninstall");
   const { dest, ide } = target(args.flags);
   const l = ledger(dest);
@@ -881,6 +887,136 @@ function listAgents(args) {
   console.log(`\n${names.length} agent(s). Install one: skilldrop install --agent <name>`);
 }
 
+/* Loops (RFC-0028): an ordered sequence of stages over existing skills, with a gate between
+   them. LOOP.md's frontmatter is already SKILL.md's shape (name + description), so a loop
+   projects into the target's skill directory as <name>/SKILL.md and becomes invokable exactly
+   like a skill. loop.json travels beside it so stages, gates and cap stay machine-readable
+   after install. A loop never contains a skill — installing one also installs the skills its
+   stages name, unless --no-skills. Optional in a catalog. */
+function loopsIn(cat) {
+  if (cat.shape === "apm") return [];
+  const d = path.join(cat.dir, "loops");
+  if (!fs.existsSync(d)) return [];
+  return fs.readdirSync(d).filter((x) => fs.existsSync(path.join(d, x, "loop.json"))).sort();
+}
+function loopDir(cat, n) { return path.join(cat.dir, "loops", n); }
+function loopSpec(cat, n) { return readJSON(path.join(loopDir(cat, n), "loop.json")); }
+
+function loopSkills(cat, n) {
+  const seen = [];
+  for (const st of loopSpec(cat, n).stages || [])
+    for (const sk of st.skills || [])
+      if (sk !== "*" && !seen.includes(sk)) seen.push(sk);
+  return seen;
+}
+
+function checkLoop(cat, n) {
+  const problems = [];
+  if (!fs.existsSync(path.join(loopDir(cat, n), "LOOP.md"))) problems.push("no LOOP.md — it is the entrypoint");
+  let spec;
+  try { spec = loopSpec(cat, n); } catch (e) { return problems.concat("loop.json is missing or unparseable"); }
+  if (spec.name !== n) problems.push(`loop.json name '${spec.name}' != folder '${n}'`);
+  if (!Array.isArray(spec.stages) || !spec.stages.length) problems.push("no stages — a loop with none sequences nothing");
+  for (const sk of loopSkills(cat, n))
+    if (!skillExists(cat, sk)) problems.push(`stage names skill '${sk}', which is not in this catalog`);
+  return problems;
+}
+
+function listLoops(args) {
+  const cat = resolveCatalog(args.flags.from);
+  const names = loopsIn(cat);
+  if (args.flags.json)
+    return emitJSON({
+      catalog: cat.source, count: names.length,
+      loops: names.map((n) => {
+        const sp = loopSpec(cat, n);
+        return { name: n, kind: sp.kind, cap: sp.cap ?? 3, description: sp.description,
+                 stages: (sp.stages || []).map((st) => ({ id: st.id, type: st.type, skills: st.skills,
+                   gate: st.gate ? { id: st.gate.id, kind: st.gate.kind } : null })) };
+      }),
+    });
+  if (!names.length) return console.log(`catalog '${cat.source}' ships no loops.`);
+  for (const n of names) {
+    const sp = loopSpec(cat, n);
+    const gates = (sp.stages || []).filter((st) => st.gate).map((st) => `${st.gate.id}:${st.gate.kind}`);
+    console.log(`${n}  [${sp.kind}, cap ${sp.cap ?? 3}]`);
+    console.log(`  ${(sp.stages || []).map((st) => st.id).join(" -> ")}`);
+    console.log(`  gates: ${gates.join(", ") || "none"}`);
+  }
+  console.log(`\n${names.length} loop(s). Install one: skilldrop install --loop <name>`);
+}
+
+function installLoops(args) {
+  const cat = resolveCatalog(args.flags.from);
+  const available = loopsIn(cat);
+  if (!available.length) die(`catalog '${cat.source}' ships no loops`);
+  let names = args._.slice();
+  if (!names.length && args.flags.pack) {
+    const ps = packsOf(cat);
+    if (!ps) die(`catalog '${cat.source}' has no packs.json`);
+    const pk = ps[args.flags.pack];
+    if (!pk) die(`unknown pack '${args.flags.pack}' in catalog '${cat.source}'`);
+    names = (pk.loops || []).slice();
+    if (!names.length) die(`pack '${args.flags.pack}' declares no loops`);
+  }
+  if (!names.length && args.flags.all) names = available.slice();
+  if (!names.length) die("nothing to install — pass loop names, --pack <name>, or --all");
+  for (const n of names) if (!available.includes(n)) die(`unknown loop '${n}' in catalog '${cat.source}'`);
+
+  let bad = 0;
+  for (const n of names) {
+    const problems = checkLoop(cat, n);
+    for (const pr of problems) console.error(`refused ${n}: ${pr}`);
+    if (problems.length) bad++;
+  }
+  if (bad) die(`${bad} loop(s) failed the structural check — nothing was installed`);
+
+  const { dest, ide } = target(args.flags);
+  fs.mkdirSync(dest, { recursive: true });
+  const l = ledger(dest);
+  const notes = [];
+  for (const n of names) {
+    const sp = loopSpec(cat, n);
+    const out = path.join(dest, n);
+    fs.mkdirSync(out, { recursive: true });
+    fs.copyFileSync(path.join(loopDir(cat, n), "LOOP.md"), path.join(out, "SKILL.md"));
+    fs.copyFileSync(path.join(loopDir(cat, n), "loop.json"), path.join(out, "loop.json"));
+    const note = writeWiring(ide, dest, n, sp.description);
+    if (note) notes.push(note);
+    l.data[n] = { version: sp.version || null, source: cat.source, loop: true };
+    console.log(`installed loop ${n} -> ${out}`);
+  }
+  saveLedger(l);
+
+  const wanted = [];
+  for (const n of names) for (const sk of loopSkills(cat, n)) if (!wanted.includes(sk)) wanted.push(sk);
+  if (args.flags["no-skills"]) {
+    console.log(`\n${names.length} loop(s) installed (${ide}). Skipped ${wanted.length} stage skill(s) (--no-skills).`);
+    console.log(`A loop whose stage skills are absent still runs — each stage degrades via its declared fallback.`);
+  } else if (wanted.length) {
+    console.log(`\nInstalling ${wanted.length} stage skill(s) the loop sequences.\n`);
+    const flags = Object.assign({}, args.flags);
+    delete flags.loop; delete flags.pack; delete flags.all;
+    install({ _: wanted, flags });
+  }
+  if (notes.length) console.log(`\n${notes.join("\n")}`);
+  console.log(`\nRun a loop by name — e.g. "run the ${names[0]} loop on this". Its SKILL.md is the script; honour each gate and the cap.`);
+}
+
+function uninstallLoops(args) {
+  if (!args._.length) die("pass loop names to uninstall");
+  const { dest, ide } = target(args.flags);
+  const l = ledger(dest);
+  for (const n of args._) {
+    fs.rmSync(path.join(dest, n), { recursive: true, force: true });
+    const w = wiringPath(ide, dest, n);
+    if (w) fs.rmSync(w, { force: true });
+    delete l.data[n];
+    console.log(`removed loop ${n} from ${dest} (stage skills left in place)`);
+  }
+  saveLedger(l);
+}
+
 function installAgents(args) {
   const cat = resolveCatalog(args.flags.from);
   const available = agentsIn(cat);
@@ -1019,7 +1155,7 @@ function validateCmd(args) {
 
 const args = parseArgs(process.argv.slice(2));
 const cmd = args._.shift();
-const commands = { list, info, packs: listPacks, agents: listAgents, install, update, outdated, uninstall, validate: validateCmd, scan };
+const commands = { list, info, packs: listPacks, agents: listAgents, loops: listLoops, install, update, outdated, uninstall, validate: validateCmd, scan };
 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/contracts/agent.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/sananthanarayan/skilldrop/contracts/agent.schema.json",
+  "title": "skilldrop reviewer subagent frontmatter",
+  "$comment": "RFC-0012 / RFC-0029. agents/<name>.md is a single markdown file whose YAML frontmatter is already Claude Code's format; the body is the system prompt. The CLI projects this into each target's own shape (Kiro JSON, Codex TOML, Copilot .agent.md), so these four fields are the portable core.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "description"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Must equal the filename stem. A rename that misses one silently breaks every delegation pointing here."
+    },
+    "description": {
+      "type": "string",
+      "description": "What routes a delegation to this agent. Required — without it the agent is unreachable."
+    },
+    "tools": {
+      "type": "string",
+      "description": "Comma-separated tool names. Recommended; the CLI maps these per target and warns where a tool has no equivalent."
+    },
+    "model": {
+      "type": "string",
+      "description": "Recommended. A hint the target may honour or ignore."
+    }
+  }
+}

package/contracts/guide.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/sananthanarayan/skilldrop/contracts/guide.schema.json",
+  "title": "skilldrop guide frontmatter",
+  "$comment": "RFC-0029. Diátaxis `kind` is a PAGE CONTRACT, not a directory requirement — the directory is a convenience, the frontmatter is the truth. That keeps the tree shallow while still forcing each page to declare what kind of document it is, which is the discipline Diátaxis actually provides.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["title", "summary", "kind"],
+  "properties": {
+    "title": { "type": "string", "description": "Sentence case. Becomes the page's single h1." },
+    "summary": { "type": "string", "description": "One line, shown in the guides index." },
+    "kind": {
+      "enum": ["tutorial", "how-to", "reference", "explanation"],
+      "description": "tutorial = learning by doing. how-to = a task with a goal. reference = look it up. explanation = why it is this way. A page that cannot pick one is doing two jobs and should be split."
+    },
+    "status": { "enum": ["draft", "review", "stable", "deprecated"], "default": "stable" }
+  }
+}

package/contracts/pack.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/sananthanarayan/skilldrop/contracts/pack.schema.json",
+  "title": "skilldrop packs.json",
+  "$comment": "RFC-0001 / RFC-0026 / RFC-0029. Packs and outcomes are METADATA ONLY — skills never move out of flat skills/<name> folders. Packs answer WHO needs a skill; outcomes answer WHY someone opened the catalogue. Both get the same two-way membership check in validate.py.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "packs", "outcomes"],
+  "properties": {
+    "$comment": { "type": "string" },
+    "version": { "type": "string" },
+    "packs": {
+      "type": "object",
+      "description": "Role-based bundles. Keys are pack names.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["description", "skills"],
+        "properties": {
+          "description": { "type": "string", "description": "One line — who this pack is for." },
+          "skills": { "type": "array", "items": { "type": "string" }, "minItems": 1,
+                      "description": "Real skill folders. Every skill must appear in at least one pack." },
+          "loops": { "type": "array", "items": { "type": "string" },
+                     "description": "RFC-0028. Real loops/ folders. Every loop must appear in at least one pack." }
+        }
+      }
+    },
+    "outcomes": {
+      "type": "object",
+      "description": "The catalogue's second browse axis. A browse aid only — never an install unit; the CLI takes no --outcome.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["description", "skills"],
+        "properties": {
+          "description": { "type": "string", "description": "The chip's tooltip on the catalogue site." },
+          "skills": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+        }
+      }
+    }
+  }
+}

package/contracts/skill.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/sananthanarayan/skilldrop/contracts/skill.schema.json",
+  "title": "skilldrop skill manifest",
+  "$comment": "RFC-0029. This shape lived only as prose in AGENTS.md, so the one authoritative statement of what a manifest is was a paragraph a contributor had to read and obey. It is now data. Checked by hand-rolled stdlib code in validate.py — skilldrop ships zero runtime dependencies and this file must not become a reason to add `jsonschema`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "version", "description", "entrypoint", "deps", "env", "related", "tags", "model"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Kebab-case. Must equal the folder name AND the SKILL.md frontmatter name — the triple-match in golden rule 1."
+    },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "description": {
+      "type": "string",
+      "description": "The most-read string in the skill. Use-case-first: what it does, then the trigger phrases an agent matches on. Must match the SKILL.md frontmatter description."
+    },
+    "entrypoint": { "const": "SKILL.md" },
+    "deps": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["npm", "pip"],
+      "properties": {
+        "npm": { "type": "array", "items": { "type": "string" } },
+        "pip": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "env": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["required", "optional"],
+      "properties": {
+        "required": { "type": "array", "items": { "type": "string" },
+                      "description": "Vars the skill cannot work without, e.g. FIGMA_TOKEN." },
+        "optional": { "type": "array", "items": { "type": "string" },
+                      "description": "Vars that change behaviour but do not block." }
+      }
+    },
+    "related": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Undirected: every sibling this SKILL.md references, in either direction. validate.py enforces the sync both ways."
+    },
+    "handoff": {
+      "type": "array",
+      "description": "RFC-0028. The directed companion to `related`. Every `to` must also appear in `related`.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["to", "when", "purpose", "fallback"],
+        "properties": {
+          "to": { "type": "string", "description": "A skill folder name. Never this skill." },
+          "when": { "type": "string", "description": "The condition under which the hand-off fires." },
+          "purpose": { "type": "string", "description": "What the target does with what it receives." },
+          "fallback": { "type": "string", "description": "What to do when the target is not installed. Required — this is what makes an advisory hand-off degrade in a stated way instead of dead-ending." }
+        }
+      }
+    },
+    "tags": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "model": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tier", "rationale"],
+      "properties": {
+        "tier": {
+          "enum": ["light", "standard", "heavy"],
+          "description": "Abstract and provider-neutral. Never a vendor model name — the provider map in model-routing.json is the only place concrete models live. Must agree with this skill's entry there."
+        },
+        "rationale": { "type": "string", "description": "One sentence: why this tier fits what the skill does." }
+      }
+    },
+    "install": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Human-readable install lines for a skill with runtime deps.",
+      "properties": { "npm": { "type": "string" }, "pip": { "type": "string" } }
+    },
+    "hooks": {
+      "type": "array",
+      "description": "RFC-0006. Only for loop-shaped skills that benefit from event automation; artifact generators carry none.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["event", "action", "description"],
+        "properties": {
+          "event": { "enum": ["session-start", "pre-commit-review", "on-demand"] },
+          "action": { "type": "string", "description": "A real skill folder this hook points at." },
+          "description": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.11.7",
+  "version": "0.11.9",
   "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.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs.json

@@ -4,6 +4,7 @@
   "packs": {
     "solution-architect": {
       "description": "Design-phase artifacts: diagrams, decision records, design docs, contracts, schemas, threat models, and the reviews that gate them.",
+      "loops": ["design", "ship-a-draft"],
       "skills": [
         "brief-intake",
         "architecture-diagrams",
@@ -26,6 +27,7 @@
     },
     "product-manager": {
       "description": "Direction to requirements: PR/FAQs, strategy frameworks, OKRs, PRDs, journey maps, story splitting, and success measurement.",
+      "loops": ["discover", "ship-a-draft"],
       "skills": [
         "brief-intake",
         "prfaq",
@@ -44,6 +46,7 @@
     },
     "dev-team": {
       "description": "Build-and-ship loop: story implementation with adversarial review, test plans, triage, migrations, release notes, agent-policy files, and code-quality gates.",
+      "loops": ["build", "ship-a-draft"],
       "skills": [
         "agents-md-generator",
         "user-story-splitter",
@@ -63,6 +66,7 @@
     },
     "sre-oncall": {
       "description": "Operate the service: runbooks, observability design, incident communications, postmortems, and capacity/cost models.",
+      "loops": ["operate"],
       "skills": [
         "runbook-generator",
         "observability-plan",
@@ -73,6 +77,7 @@
     },
     "stakeholder-comms": {
       "description": "Non-technical audiences: audience profiling, deck outlines and real .pptx decks, exec summaries, decision logs, and guides.",
+      "loops": ["ship-a-draft"],
       "skills": [
         "brief-intake",
         "audience-profile",
@@ -87,6 +92,7 @@
     },
     "ai-engineering": {
       "description": "Adopt and build AI systems: readiness assessment, use-case triage, rollout and acceptable-use policy, plus agent loop design, subagent orchestration, spend budgets, agent security review, eval harnesses, AI-usage reporting, and the data contracts AI pipelines depend on.",
+      "loops": ["design", "build"],
       "skills": [
         "agent-loop-design",
         "subagent-design",