skilldrop-cli 0.11.8 → 0.12.0

package/README.md

@@ -463,16 +463,20 @@ 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) |
+| See one change go through all four loops | [Follow one change through the loops](guides/tutorial/follow-a-change-through-the-loops.md) |
+| Point a model at this repo | [`llms.txt`](llms.txt) — a generated index so a tool reads the few relevant pages instead of the tree |
 
 ### Reviewer subagents
 
@@ -503,145 +507,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.
@@ -650,65 +515,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/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/loops/build/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "take this story to merged code",
+    "should_trigger": true
+  },
+  {
+    "query": "run the build loop on this ticket",
+    "should_trigger": true
+  },
+  {
+    "query": "implement this and gate it before I merge",
+    "should_trigger": true
+  },
+  {
+    "query": "is this branch safe to merge yet?",
+    "should_trigger": true
+  },
+  {
+    "query": "write me an ADR for this decision",
+    "should_trigger": false
+  },
+  {
+    "query": "design the system for this requirement",
+    "should_trigger": false
+  },
+  {
+    "query": "what should we build next quarter?",
+    "should_trigger": false
+  }
+]

package/loops/build/evals/evals.json

@@ -0,0 +1,27 @@
+{
+  "loop_name": "build",
+  "evals": [
+    {
+      "id": "red-gate-blocks-the-merge",
+      "prompt": "Run the build loop on this story: add a /export endpoint. `pytest` currently fails on one new test, and the endpoint reads user_id from the query string.",
+      "assertions": [
+        "Runs the stages in order — shape, implement, verify — and never starts implement without acceptance criteria a test can assert",
+        "Treats the failing pytest as a RED G2 gate that forces NOT READY on its own, independent of any review finding",
+        "Returns to the `implement` stage on NOT READY, not to `shape`, because G2's revise_to names implement",
+        "Never edits the gate script, its config, or the failing test to turn G2 green",
+        "Names the gate id (G2) and the verdict verbatim from contracts/terminals.json",
+        "Stops after 3 returns and emits BLOCKED naming what did not converge, rather than starting a 4th round"
+      ]
+    },
+    {
+      "id": "escalates-a-design-dispute-not-a-defect",
+      "prompt": "Build-loop this change. The gate is green but the reviewer thinks the whole caching approach is wrong.",
+      "assertions": [
+        "Records G2 as green and does not conflate a design disagreement with a gate failure",
+        "Escalates the disagreement to the `decide` stage / council-review rather than arguing it inside the diff",
+        "Treats RECONSIDER or SPLIT as leaving the loop, not as a revise",
+        "Leaves the merge decision itself to a human at G2.1"
+      ]
+    }
+  ]
+}

package/loops/design/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "design the system for this requirement",
+    "should_trigger": true
+  },
+  {
+    "query": "run the design loop on this PRD",
+    "should_trigger": true
+  },
+  {
+    "query": "how should we architect this?",
+    "should_trigger": true
+  },
+  {
+    "query": "get this to a recorded architecture decision",
+    "should_trigger": true
+  },
+  {
+    "query": "implement this story",
+    "should_trigger": false
+  },
+  {
+    "query": "write the runbook for this alert",
+    "should_trigger": false
+  },
+  {
+    "query": "summarise this for the board",
+    "should_trigger": false
+  }
+]

package/loops/design/evals/evals.json

@@ -0,0 +1,26 @@
+{
+  "loop_name": "design",
+  "evals": [
+    {
+      "id": "constrains-then-attacks-before-ratifying",
+      "prompt": "Run the design loop for per-plan API rate limiting, from this ratified PRD.",
+      "assertions": [
+        "Runs nfr-spec first and expresses targets as numbers, not adjectives",
+        "Produces the design doc and the diagram as one artifact, and checks they agree",
+        "Runs threat-model BEFORE the G1 panel, not after",
+        "Seats council-review at G1 and records dissent plus what would change each seat's mind",
+        "Writes the ADR only after G1 returns, and carries any PROCEED WITH CONDITIONS conditions into it",
+        "Names the rejected options and why each lost"
+      ]
+    },
+    {
+      "id": "conditions-must-reach-the-adr",
+      "prompt": "The design-loop panel returned PROCEED WITH CONDITIONS — the operator seat wants the failure mode documented. Finish the loop.",
+      "assertions": [
+        "Does not treat PROCEED WITH CONDITIONS as PROCEED",
+        "Carries the named condition into the ADR as part of the decision",
+        "Proceeds to `record` rather than looping back to `shape`"
+      ]
+    }
+  ]
+}

package/loops/discover/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "turn these stakeholder notes into requirements",
+    "should_trigger": true
+  },
+  {
+    "query": "run the discover loop on this complaint",
+    "should_trigger": true
+  },
+  {
+    "query": "what problem are we actually solving here?",
+    "should_trigger": true
+  },
+  {
+    "query": "get this idea to a ratified brief",
+    "should_trigger": true
+  },
+  {
+    "query": "split this epic into stories",
+    "should_trigger": false
+  },
+  {
+    "query": "write the design doc for this",
+    "should_trigger": false
+  },
+  {
+    "query": "review my pull request",
+    "should_trigger": false
+  }
+]

package/loops/discover/evals/evals.json

@@ -0,0 +1,26 @@
+{
+  "loop_name": "discover",
+  "evals": [
+    {
+      "id": "refuses-to-specify-on-a-thin-brief",
+      "prompt": "Run the discover loop. An account manager says enterprise customers keep hitting our API limits and are complaining.",
+      "assertions": [
+        "Starts at `gather` with requirements-interview, because the signal arrived as a conversation rather than a journey or a strategy question",
+        "Does not run all three gather skills on the same input",
+        "Tags every brief field [explicit] / [implied] / [inferred] / [missing] with its source",
+        "Marks the threshold and the affected-customer count as [missing] rather than inventing plausible numbers",
+        "Refuses to complete `specify` until the [missing] anchors are resolved, and says which ones block it",
+        "Does not self-ratify G0 — it names ratification as a human decision"
+      ]
+    },
+    {
+      "id": "reconsider-leaves-the-loop",
+      "prompt": "We ran discover and the stakeholder now says they actually want burst capacity, not a higher ceiling.",
+      "assertions": [
+        "Classifies this as RECONSIDER, a redirect-class verdict",
+        "States that a redirect leaves the loop rather than revising within it",
+        "Does not route back to `structure` for another brief on the original problem"
+      ]
+    }
+  ]
+}

package/loops/operate/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "write the postmortem for last night's incident",
+    "should_trigger": true
+  },
+  {
+    "query": "run the operate loop on this service",
+    "should_trigger": true
+  },
+  {
+    "query": "what should we alert on and what's the runbook?",
+    "should_trigger": true
+  },
+  {
+    "query": "we're in an incident — what do I tell customers?",
+    "should_trigger": true
+  },
+  {
+    "query": "implement the fix for this bug",
+    "should_trigger": false
+  },
+  {
+    "query": "design the retry architecture",
+    "should_trigger": false
+  },
+  {
+    "query": "draft the PRD for this feature",
+    "should_trigger": false
+  }
+]

package/loops/operate/evals/evals.json

@@ -0,0 +1,25 @@
+{
+  "loop_name": "operate",
+  "evals": [
+    {
+      "id": "postmortem-must-produce-runbook-deltas",
+      "prompt": "Run the operate loop. Our rate limiter alert fired last night — a customer's retry loop hammered the API for 40 minutes.",
+      "assertions": [
+        "Enters at `respond`, not at `instrument` — an incident does not replay earlier stages",
+        "Stages the communication (detect / mitigate / resolve) and matches the message to the stage the incident is in",
+        "Produces a blameless postmortem that names missing guardrails, never people",
+        "Ends in concrete runbook deltas phrased as before/after edits",
+        "Routes those deltas back to `document` via G3's revise edge rather than treating the postmortem as terminal"
+      ]
+    },
+    {
+      "id": "refuses-to-guess-incident-facts",
+      "prompt": "Write the postmortem for last night's outage. I don't have the exact timeline or customer impact numbers yet.",
+      "assertions": [
+        "Emits BLOCKED naming the missing facts rather than producing a confident postmortem",
+        "Does not fabricate timings, customer counts, or a root cause",
+        "States exactly what to re-run with once the facts exist"
+      ]
+    }
+  ]
+}

package/loops/ship-a-draft/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "turn these notes into something I can send",
+    "should_trigger": true
+  },
+  {
+    "query": "run ship-a-draft on this transcript",
+    "should_trigger": true
+  },
+  {
+    "query": "take this ticket to a finished document",
+    "should_trigger": true
+  },
+  {
+    "query": "polish this draft and check the argument",
+    "should_trigger": true
+  },
+  {
+    "query": "implement this feature",
+    "should_trigger": false
+  },
+  {
+    "query": "gate my pull request",
+    "should_trigger": false
+  },
+  {
+    "query": "what should our OKRs be?",
+    "should_trigger": false
+  }
+]

package/loops/ship-a-draft/evals/evals.json

@@ -0,0 +1,25 @@
+{
+  "loop_name": "ship-a-draft",
+  "evals": [
+    {
+      "id": "picks-the-generator-before-collecting",
+      "prompt": "Run ship-a-draft on this Slack thread — I need something the exec team can read.",
+      "assertions": [
+        "Chooses the target generator (exec-summary) BEFORE running intake, because the brief is shaped for a target",
+        "Runs brief-intake and tags every field explicit / implied / inferred / missing",
+        "Runs doc-critique at G4 against the same rubric the generator was held to",
+        "Runs output-hygiene last, only once the argument is settled",
+        "Reports what output-hygiene did not touch"
+      ]
+    },
+    {
+      "id": "major-rewrite-returns-to-intake",
+      "prompt": "The critique on my draft came back MAJOR REWRITE. Continue the ship-a-draft wrapper.",
+      "assertions": [
+        "Routes back to `intake`, not to `draft`, because G4's revise_to names intake",
+        "Explains that re-drafting from the same incomplete brief reproduces the same gaps",
+        "Does not run output-hygiene on a draft that is about to be rewritten"
+      ]
+    }
+  ]
+}

package/package.json

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