skilldrop-cli 0.7.0 → 0.8.1

package/README.md

@@ -151,6 +151,8 @@ Designing the agentic systems themselves — the loops, orchestrations, and budg
 | [`agent-budget`](skills/agent-budget/SKILL.md) | The spend spec for an agentic workflow: cheapest-adequate **tier per stage** (light/standard/heavy — heavy verification is never downgraded to save money), three numbers per stage (expected, hard cap, on-cap action — "warn and continue" banned), a run-level cap *below* the sum of stage caps, a **degradation ladder where verification is last and never cut**, and **cost-per-outcome** as the governing metric with a comparison line against the manual alternative — so "$900/week" becomes answerable. Estimates tagged `[assumption]` until calibrated on real runs. |
 | [`agent-threat-model`](skills/agent-threat-model/SKILL.md) | Security review of an agent's **capability surface** against the lethal trifecta — private data, untrusted content, an exfiltration vector. Inventories data reach *transitively* (the filesystem tool reaches every secret in `.env`), applies a writer-authorization test that classifies almost every content source untrusted, and sweeps egress past the obvious network tool (rendered markdown images, CI logs, error text, DNS). Scores **paths, not tools** — `fetch` is fine alone and lethal beside a secrets file — then names the architectural fix that breaks a leg, with a verification step. Structurally refuses the two answers teams reach for first: a system prompt telling the model to ignore injected instructions is not a control, and an injection classifier is defense in depth, never a broken leg. |
 
+| [`agents-md-generator`](skills/agents-md-generator/SKILL.md) | Generate or audit the `AGENTS.md` that Claude Code, Codex, Cursor, Copilot, Kiro and Antigravity all read before your prompt. Built around one rule: **every command traces to evidence in the repo** — a CI step, a Makefile target, a `package.json` script — or it appears as `[missing: no test command in CI or manifests]` rather than a guess, because an invented command is a fault the agent will trust over the filesystem. Convention lines must pass a **counterfactual test** (without this line, would a competent agent do the wrong thing?); virtue instructions — "clean", "best practice", "thorough" — are *stripped, not softened*, since they spend context and change no behaviour. Names forbidden actions explicitly, the section most files omit. Hard ~150-line cap when generating, a warning when auditing, because an existing file may be long for good reason. Audit mode emits a diff, never a silent rewrite. Satellites (`CLAUDE.md`, `.github/copilot-instructions.md`) are opt-in and **delta-only** — a satellite that repeats `AGENTS.md` is guaranteed drift. |
+
 ### AI adoption & observability
 
 | Skill | What it does |
@@ -293,13 +295,14 @@ Four targets, each projecting only as much as the tool's format demands:
 | `--ide copilot` | `.github/agents/<name>.agent.md` | a rename |
 | `--ide kiro` | `.kiro/agents/<name>.json` | generated JSON; tool names mapped to Kiro's built-ins |
 | `--ide codex` | `~/.codex/agents/<name>.toml` (`--project` for repo) | generated TOML |
+| `--ide antigravity` | `~/.gemini/config/agents/<name>.md` (`--project` → `.agents/agents/`) | frontmatter rewritten, `subagent: true` added |
 | `--dest <dir>` | `<dir>/<name>.md` | none |
 
 The Kiro emitter maps `Read`/`Grep`/`Glob`/`Bash` to `read`/`grep`/`glob`/`shell` against [Kiro's built-in tool reference](https://kiro.dev/docs/cli/reference/built-in-tools/), and **names any tool it can't map instead of dropping it silently** — a mistranslated permission is worse than a missing one. It omits `allowedTools` so you're prompted per tool call.
 
 Each generated target omits the permission field it cannot map safely rather than guessing one: Kiro's `allowedTools` and Codex's `sandbox_mode` are both left unset, so an agent inherits the session's permissions and is prompted per call. A widened permission nobody asked for is worse than an extra prompt.
 
-Only **Antigravity** still refuses — its subagents exist solely inside a plugin bundle, which is a container rather than a file drop. Design is worked out in [RFC-0013](docs/rfcs/0013-antigravity-plugin-bundle.md), unimplemented pending demand. [`agents/README.md`](agents/README.md) has the manual route.
+**Every surveyed tool now installs.** Only Cursor is absent, because it has no agent file format at all — use a custom mode ([`agents/README.md`](agents/README.md) has the steps).
 
 ### Third-party catalogs — publish your own skills through the same CLI
 

package/agents/README.md

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

package/bin/skilldrop.js

@@ -54,8 +54,9 @@ Options:
                        --ide kiro     ./.kiro/agents        generated JSON, tools mapped
                        --ide copilot  ./.github/agents      <name>.agent.md
                        --ide codex    ~/.codex/agents       generated TOML (--project for repo)
+                       --ide antigravity  ~/.gemini/config/agents  markdown, subagent: true
                        --dest <dir>   any directory         copied as-is
-                     Antigravity needs a plugin bundle (RFC-0013) — see agents/README.md.
+                     Cursor has no agent format — use a custom mode (agents/README.md).
   --with-related     also install each skill's related companions (one level)
   --with-hooks       also wire any hooks a skill declares (RFC-0006) — git pre-commit
                      reminders and Claude Code session-start context; degrades where the
@@ -202,6 +203,26 @@ function kiroAgentJSON(meta, body) {
   return { json: JSON.stringify(agent, null, 2) + "\n", unmapped: [...new Set(unmapped)] };
 }
 
+/* Antigravity agent markdown (RFC-0013). Only mappings confirmed in Antigravity's own
+   subagents doc are listed. There is no glob-style tool in its file tooling
+   (view_file / list_dir / grep_search / write_to_file), so Glob is dropped and named
+   rather than bent into list_dir — a different operation. */
+const ANTIGRAVITY_TOOLS = { Read: "view_file", Grep: "grep_search", Bash: "run_command" };
+const ANTIGRAVITY_MODELS = new Set(["inherit", "flash", "pro"]);
+
+function antigravityAgentMD(meta, body) {
+  const declared = meta.tools ? meta.tools.split(",").map((s) => s.trim()).filter(Boolean) : [];
+  const tools = [], unmapped = [];
+  for (const d of declared) (ANTIGRAVITY_TOOLS[d] ? tools : unmapped).push(ANTIGRAVITY_TOOLS[d] || d);
+  // YAML double-quoted scalars are a superset of JSON strings, so JSON.stringify is a
+  // correct quoter here — descriptions contain em-dashes and embedded quotes.
+  const lines = [`name: ${JSON.stringify(meta.name)}`, `description: ${JSON.stringify(meta.description)}`];
+  if (tools.length) lines.push(`tools: [${tools.join(", ")}]`);
+  lines.push("subagent: true"); // required, or invoke_subagent cannot reach it
+  if (ANTIGRAVITY_MODELS.has(meta.model)) lines.push(`model: ${meta.model}`);
+  return { md: `---\n${lines.join("\n")}\n---\n\n${body}\n`, unmapped: [...new Set(unmapped)] };
+}
+
 /* Codex agent TOML. Schema confirmed at learn.chatgpt.com/docs/agent-configuration/subagents:
    name, description and developer_instructions are required; unknown fields are rejected.
    sandbox_mode is deliberately NOT emitted — Codex has no `tools` field, permissions come
@@ -219,7 +240,6 @@ function codexAgentTOML(meta, body) {
 /* 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 = {
-  antigravity: "an agents/ directory inside a plugin bundle you own — see RFC-0013",
   cursor: "a custom mode — Cursor has no agent file format",
 };
 function agentTarget(flags) {
@@ -236,6 +256,10 @@ function agentTarget(flags) {
     return flags.project
       ? { dest: path.resolve(".codex", "agents"), ide }
       : { dest: path.join(os.homedir(), ".codex", "agents"), ide };
+  if (ide === "antigravity")
+    return flags.project
+      ? { dest: path.resolve(".agents", "agents"), ide }
+      : { dest: path.join(os.homedir(), ".gemini", "config", "agents"), ide };
   const hint = AGENT_MANUAL[ide];
   die(`--agent has no target for '${ide}'${hint ? ` — it needs ${hint}` : ""}.\n` +
       `       Copy it by hand (see agents/README.md), or use --dest <dir>. Tracked in RFC-0012.`);
@@ -254,6 +278,15 @@ function writeAgent(cat, a, dest, ide) {
       ? `  ${a}: no Kiro equivalent for ${unmapped.join(", ")} — dropped from tools, add by hand if needed`
       : null };
   }
+  if (ide === "antigravity") {
+    const raw = fs.readFileSync(src, "utf8");
+    const body = raw.split("---").slice(2).join("---").trim();
+    const { md, unmapped } = antigravityAgentMD(agentMeta(cat, a), body);
+    fs.writeFileSync(path.join(dest, `${a}.md`), md);
+    return { file: `${a}.md`, warn: unmapped.length
+      ? `  ${a}: no Antigravity equivalent for ${unmapped.join(", ")} — dropped from tools, add by hand if needed`
+      : null };
+  }
   if (ide === "codex") {
     const raw = fs.readFileSync(src, "utf8");
     const body = raw.split("---").slice(2).join("---").trim();
@@ -585,6 +618,7 @@ function installAgents(args) {
   if (ide === "kiro") console.log("Kiro grants `tools` but not auto-approval — you are prompted per call by design.");
   if (ide === "copilot") console.log("Invoke with: copilot --agent <name>");
   if (ide === "codex") console.log("sandbox_mode is left unset, so each agent inherits the parent session's permissions.");
+  if (ide === "antigravity") console.log("Emitted with `subagent: true` so invoke_subagent can reach them.");
   if (cat.source !== BUNDLED)
     console.log(`\nWARNING: third-party catalog '${cat.source}'. An agent is a system prompt your tool will adopt — read it before first use. Install copied files only; nothing was executed.`);
 }

package/model-routing.json

@@ -146,6 +146,7 @@
     "agent-loop-design": { "tier": "standard", "rationale": "Design synthesis against a fixed state-machine pattern and exit-criteria catalog. The gate-placement judgment is bounded by the blast-radius rule; escalate via ambiguous-input when the task itself is contested." },
     "subagent-design": { "tier": "standard", "rationale": "Design synthesis against a fixed topology catalog and role-card template. The fan-out-or-refuse judgment is bounded by the three-reasons rule; escalate via ambiguous-input on genuinely novel workflow shapes." },
     "agent-budget": { "tier": "standard", "rationale": "Quantitative spec synthesis against a fixed tier vocabulary and degradation ladder. Cap-setting judgment is bounded by the 3-5x rule; escalate via ambiguous-input when the workflow itself is undefined." },
+    "agents-md-generator": { "tier": "standard", "rationale": "Repo inspection plus synthesis against a fixed section order and line budget — the same shape as reverse-architecture. The judgment is the counterfactual test on each convention line, which is bounded; escalate via large-input on monorepos." },
     "agent-threat-model": { "tier": "heavy", "rationale": "Adversarial reasoning over a capability graph — the judgment is which mitigations are architectural versus theatrical, and that call is exactly where a weaker model produces a confident wrong answer. Never downgraded." }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "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"

package/packs.json

@@ -14,6 +14,7 @@
         "tech-comparison-matrix",
         "threat-model",
         "agent-threat-model",
+        "agents-md-generator",
         "api-contract-draft",
         "data-contract",
         "db-schema-design",
@@ -41,8 +42,9 @@
       ]
     },
     "dev-team": {
-      "description": "Build-and-ship loop: story implementation with adversarial review, test plans, triage, migrations, release notes, and code-quality gates.",
+      "description": "Build-and-ship loop: story implementation with adversarial review, test plans, triage, migrations, release notes, agent-policy files, and code-quality gates.",
       "skills": [
+        "agents-md-generator",
         "user-story-splitter",
         "feature-implement-loop",
         "devils-advocate",

package/skills/agents-md-generator/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: agents-md-generator
+description: Generate or audit a repository's AGENTS.md — the agent-policy file Claude Code, Codex, Cursor, Copilot, Kiro and Antigravity read — with every command traced to real evidence in the repo, generic virtue instructions stripped, and forbidden actions named. Use when a repo has no AGENTS.md, when an existing one is stale or ignored, when onboarding a codebase to agentic coding, or when an agent keeps running commands that don't exist.
+---
+
+# agents-md-generator
+
+Produces the file agents read *before* the user's prompt. An `AGENTS.md` is not documentation — it is the context an agent spends on every turn, so a line that changes no decision is a line stolen from the task.
+
+The failure that makes these files worse than useless is an **invented command**. `npm test` in a repo with no test script sends every agent down a path that fails, and the agent trusts the file over the filesystem. So the rule this skill is built around: **every command traces to evidence in the repo, or it does not appear.**
+
+Two modes, chosen by what's already there:
+- **Generate** — no `AGENTS.md` exists. Produce one under the line cap.
+- **Audit** — one exists. Score it, name what can't be verified, emit a diff. Never silently rewrite a hand-tuned file.
+
+## How to respond
+
+1. **Inventory the real command surface before writing anything.** Read, in this order: `package.json` (`scripts`), `Makefile`, `pyproject.toml` / `setup.cfg`, `Cargo.toml`, `go.mod`, `composer.json`, `.github/workflows/*.yml`, `justfile`, `Taskfile.yml`, and any `CONTRIBUTING.md`. CI workflows are the highest-value source: they contain the commands that actually have to pass.
+
+   For each command record its **provenance** — the file and key it came from. Provenance is what makes audit mode possible later.
+
+2. **Apply the evidence rule without exception.** A command appears only if it traces to a file in the repo. Never infer from ecosystem convention: a Python repo does not necessarily run `pytest`, and a repo with `jest` in `devDependencies` may still have no test script.
+
+   When a section needs a command that doesn't exist, write the marker, not a guess: ✅ *"Test: `[missing: no test script in package.json or CI]`"* — ❌ *"Test: `npm test`"*. The marker is useful; the guess is a trap.
+
+3. **Derive file placement from the actual tree**, not from what the framework usually does. Name the directories that exist and what belongs in each. Two or three rows beat a full tree dump.
+
+4. **Extract only conventions an agent would otherwise get wrong.** The test is counterfactual: *would a competent agent, without this line, do the wrong thing?* Naming rules that are enforced somewhere, invariants that look arbitrary but aren't, a generated file that must never be hand-edited. If the answer is no, cut the line.
+
+   Generic virtue instructions — "write clean code", "be thorough", "follow best practices", "use good naming" — are **stripped, not softened.** They consume context and change no behaviour.
+
+5. **Name forbidden actions explicitly.** This is the section most files omit and the one that prevents the most damage: paths that must not be touched, commands that must never run unattended, files that are generated, secrets that must never be committed. Concrete and few.
+
+6. **Assemble under ~150 lines.** In generate mode this is a **hard cap** — go over and cut, lowest value first (background prose, then examples, then convention lines that failed the counterfactual test). In audit mode it is a **warning**: report the overage and name the sections you would cut, because an existing file may be long for good reason.
+
+7. **Satellites only on request, and only as a delta.** If asked to wire a specific tool, emit a satellite (`CLAUDE.md`, `.github/copilot-instructions.md`, `GEMINI.md`) that contains **only what is specific to that tool**, plus one line pointing at `AGENTS.md` for everything shared. **Refuse to copy shared content into a satellite** — four copies of a command list is four chances to be wrong, and the drift is invisible. See [`reference.md`](reference.md) for the per-tool shapes.
+
+8. **Emit.** Generate mode: the file, plus a provenance table showing where each command came from and what was marked `[missing]`. Audit mode: verdict, the unverifiable lines quoted, the virtue instructions to cut, the line-count position, and a concrete diff.
+
+**Non-interactive runs:** unstated conventions are simply omitted — an `AGENTS.md` is allowed to be short. If the repo cannot be read at all, emit `BLOCKED: need repo access — every command must trace to a file`. Never produce an `AGENTS.md` from a description of a repo; the whole artifact is a claim about what is in the tree.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — where each tool looks, the evidence-source table, the satellite shapes, and the strip-list of virtue phrasings
+- [`templates/agents-md.md`](templates/agents-md.md) — the output skeleton with the section order and the line budget per section
+
+## Quality bar
+
+- **Zero unverified commands.** Every one traces to a file and key, or carries a `[missing: …]` marker. This is the bar; a file that fails it is worse than no file.
+- **A newcomer agent could build and test from this file alone** — or can see plainly that the repo has no such command.
+- **Forbidden actions are named**, not implied.
+- **Every convention line passes the counterfactual test.** If an agent would do the right thing without it, it is padding.
+- **≤150 lines generated.** Over the cap means something was kept that should have been cut.
+- **No virtue instructions survive.** Search the output for "clean", "best practice", "thorough", "appropriate", "as needed" — each hit is a line that changes nothing.
+- **It does not restate the README.** Different reader, different job: the README sells and explains, `AGENTS.md` constrains.
+
+## When to use this skill
+
+- ✅ A repo is adopting agentic coding and has no `AGENTS.md`
+- ✅ An existing `AGENTS.md` is stale, ignored, or full of advice rather than facts
+- ✅ Agents keep running commands that don't exist in the repo
+- ✅ Onboarding a legacy codebase where the real commands live only in CI
+- ✅ After `reverse-architecture` — its extraction is good input for the conventions section
+
+## When NOT to use this skill
+
+- ❌ Writing human contributor docs — that's `CONTRIBUTING.md`, a different reader
+- ❌ Explaining what the project *is* — that's the README
+- ❌ Operating a running service — that's `runbook-generator`
+- ❌ Reviewing an existing document's prose quality — that's `doc-critique`, which takes documents; this one takes a repository
+
+## Anti-patterns to avoid
+
+- ❌ **Inventing a command that "should" exist.** The single most damaging thing this artifact can do. A `[missing]` marker is a finding; a guess is a fault the agent will trust.
+- ❌ **Virtue instructions.** "Write clean, maintainable code" is context spent on nothing. Agents already try.
+- ❌ **Dumping the file tree.** Placement rules earn their space; a directory listing does not — the agent can run `ls`.
+- ❌ **Restating the README.** If it's already there, link it.
+- ❌ **A satellite that duplicates `AGENTS.md`.** Guaranteed drift, invisible until an agent acts on the stale copy.
+- ❌ **Silently rewriting a hand-tuned file.** Audit mode emits a diff and lets a human choose; the file may encode decisions the repo can't show you.
+- ❌ **Writing to the cap.** 150 lines is a ceiling, not a target. Most repos need far less.

package/skills/agents-md-generator/evals/eval_queries.json

@@ -0,0 +1,15 @@
+[
+  { "query": "Write an AGENTS.md for this repo", "should_trigger": true },
+  { "query": "Our AGENTS.md is stale — review it", "should_trigger": true },
+  { "query": "The agent keeps running commands that don't exist in our project", "should_trigger": true },
+  { "query": "Set this codebase up for agentic coding", "should_trigger": true },
+  { "query": "Create a CLAUDE.md for this project", "should_trigger": true },
+  { "query": "What should go in an agent instructions file?", "should_trigger": true },
+
+  { "query": "Write a CONTRIBUTING.md for this repo", "should_trigger": false },
+  { "query": "Document what this service does for new hires", "should_trigger": false },
+  { "query": "Reverse-engineer the architecture of this codebase", "should_trigger": false },
+  { "query": "Write a runbook for this service", "should_trigger": false },
+  { "query": "Review this design doc for gaps", "should_trigger": false },
+  { "query": "Design a supervised agent loop", "should_trigger": false }
+]

package/skills/agents-md-generator/evals/evals.json

@@ -0,0 +1,50 @@
+{
+  "skill_name": "agents-md-generator",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write an AGENTS.md for this repo. It's a Python service: pyproject.toml declares pytest and ruff in dev dependencies, there's a Makefile with `run` and `migrate` targets, and .github/workflows/ci.yml runs `ruff check .` then `pytest -q`. No test script anywhere else. Migrations are in alembic/versions/.",
+      "assertions": [
+        "Commands are traced to their source — CI for ruff/pytest, Makefile for run/migrate — not inferred from the dependency list",
+        "The test command is `pytest -q` as CI runs it, not a guessed `pytest` or `make test` that does not exist",
+        "No command appears that cannot be traced to pyproject.toml, the Makefile, or the workflow",
+        "Alembic migrations produce a convention or forbidden-action line (append-only / never edit a committed migration)",
+        "A `Do not` section exists with concrete entries, not implied caution",
+        "Output is at or under ~150 lines",
+        "No virtue instructions appear — no 'clean', 'best practice', 'thorough', 'maintainable'",
+        "Conventions included would each change agent behaviour if removed"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Here's our AGENTS.md — audit it. It says: 'Run `npm test` to test. Write clean, maintainable code and follow best practices. Be thorough in reviews.' Our package.json has scripts for build and lint only, no test.",
+      "assertions": [
+        "Audit mode is used — a verdict and diff, not a silent rewrite",
+        "`npm test` is flagged as unverifiable: package.json has no test script",
+        "The three virtue instructions are named for removal, with the reason that they change no behaviour",
+        "What the file is missing is stated — real commands (build, lint), file placement, forbidden actions",
+        "The line-count position is reported rather than the file being failed for length",
+        "A concrete replacement or diff is offered, not just criticism"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Also wire it up for Claude Code and Copilot.",
+      "assertions": [
+        "Satellites are emitted as deltas only — each points at AGENTS.md for shared content",
+        "No satellite repeats the command table, file placement, or conventions",
+        "CLAUDE.md carries only Claude-Code-specific content; .github/copilot-instructions.md only Copilot-specific content",
+        "If there is no genuinely tool-specific content, that is said rather than a file padded to justify itself"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "[Non-interactive run — no repo access] Generate an AGENTS.md for a typical Node microservice.",
+      "assertions": [
+        "No AGENTS.md is produced — the output is BLOCKED: need repo access",
+        "No commands are invented from ecosystem convention",
+        "The reason given is that every command must trace to a file in the tree"
+      ]
+    }
+  ]
+}

package/skills/agents-md-generator/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "agents-md-generator",
+  "version": "0.1.0",
+  "description": "Generate or audit a repository's AGENTS.md — the agent-policy file Claude Code, Codex, Cursor, Copilot, Kiro and Antigravity read — with every command traced to real evidence in the repo, generic virtue instructions stripped, and forbidden actions named. Use when a repo has no AGENTS.md, when an existing one is stale or ignored, when onboarding a codebase to agentic coding, or when an agent keeps running commands that don't exist.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["doc-critique", "reverse-architecture", "runbook-generator"],
+  "tags": ["agents-md", "agent-policy", "repo-onboarding", "context-engineering", "agentic", "conventions"],
+  "model": { "tier": "standard", "rationale": "Repo inspection plus synthesis against a fixed section order and line budget — the same shape as reverse-architecture. The judgment is the counterfactual test on each convention line, which is bounded; escalate via large-input on monorepos." }
+}

package/skills/agents-md-generator/reference.md

@@ -0,0 +1,89 @@
+# agents-md-generator — reference
+
+## Who reads what
+
+Confirmed in the July 2026 survey ([`docs/designs/ide-primitive-coverage.md`](../../docs/designs/ide-primitive-coverage.md)). A root `AGENTS.md` is the broadest single file; satellites are a reach fix for specific tools, not the norm.
+
+| Tool | Reads |
+|---|---|
+| Codex | root `AGENTS.md` |
+| GitHub Copilot | root `AGENTS.md`, `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, and also root `CLAUDE.md` / `GEMINI.md` |
+| Claude Code | `CLAUDE.md` (auto-loaded) |
+| Cursor | root `AGENTS.md`, plus `.cursor/rules/*.mdc` for rules |
+| Kiro | root `AGENTS.md`, plus `.kiro/steering/` for always-on context |
+| Antigravity | root `AGENTS.md` |
+
+**Precedence matters more than reach.** Several of these load on every turn regardless of relevance. A file that is always in context should carry only what earns its place there — the same reason an always-included steering file is a poor home for a persona.
+
+## Evidence sources, in priority order
+
+Every command must trace to one of these. Record the file and key as provenance.
+
+| Source | What it proves |
+|---|---|
+| `.github/workflows/*.yml` (and other CI) | **Strongest.** These commands must pass or the build fails |
+| `Makefile` / `justfile` / `Taskfile.yml` | Named entry points the team actually uses |
+| `package.json` `scripts` | Node entry points; check the script body, not just the key |
+| `pyproject.toml` / `setup.cfg` / `tox.ini` | Python entry points and runners |
+| `Cargo.toml`, `go.mod`, `composer.json`, `Gemfile` | Ecosystem defaults *only if* the file confirms them |
+| `CONTRIBUTING.md`, `README.md` | Human-facing; **verify against the above before trusting** — docs go stale faster than CI |
+| Dev container / Dockerfile | Setup steps and version pins |
+
+**A dependency is not a command.** `jest` in `devDependencies` does not mean `npm test` exists. Check for the script.
+
+## What earns a line — the counterfactual test
+
+Ask: *without this line, would a competent agent do the wrong thing?*
+
+| ✅ Earns its place | ❌ Cut |
+|---|---|
+| "Generated — never hand-edit `src/api/types.ts`; run `make codegen`" | "Keep the codebase clean and well organised" |
+| "Migrations are append-only; never edit a committed migration" | "Follow database best practices" |
+| "Tests live beside the source as `*_test.go`, not in `tests/`" | "Write comprehensive tests" |
+| "`main` is protected; open a PR" | "Follow good git hygiene" |
+| "Do not run `terraform apply` — plan only, a human applies" | "Be careful with infrastructure" |
+
+## Strip list
+
+Search generated output for these; each hit is a line that changes no behaviour:
+
+`clean` · `best practice` · `thorough` · `appropriate` · `as needed` · `where possible` · `make sure to` · `try to` · `robust` · `maintainable` · `readable` · `well-structured` · `properly` · `high-quality` · `idiomatic` (unless a specific idiom is named)
+
+## Satellite shapes — delta only
+
+A satellite carries what is specific to its tool **and nothing else**. Every shared fact stays in `AGENTS.md` and is pointed at.
+
+**`CLAUDE.md`** — Claude Code auto-loads it:
+
+```markdown
+# CLAUDE.md
+
+The substantive guidance lives in [AGENTS.md](AGENTS.md). Read it first.
+
+This file exists because Claude Code auto-loads `CLAUDE.md`. Everything below is
+Claude-Code-specific and does not belong in the cross-IDE file.
+
+## <tool-specific section>
+…e.g. `${CLAUDE_SKILL_DIR}` semantics, `.claude/settings.json`, subagent delegation…
+```
+
+**`.github/copilot-instructions.md`** — same shape, Copilot-specific content only (custom agents in `.github/agents/`, `.github/hooks/*.json`).
+
+**`GEMINI.md`** — same shape, for Gemini/Antigravity specifics.
+
+**Refuse** to emit a satellite containing the command table, file placement, or conventions that already live in `AGENTS.md`. If a tool needs those, it reads `AGENTS.md` — and if it genuinely cannot, say so plainly rather than duplicating.
+
+## Line budget
+
+150 lines total. A workable split:
+
+| Section | Lines |
+|---|---|
+| Repo in one paragraph | 3–5 |
+| Commands (with provenance verified) | 15–30 |
+| File placement | 10–20 |
+| Conventions that pass the counterfactual test | 20–40 |
+| Forbidden actions | 5–15 |
+| Pointers to deeper docs | 3–5 |
+
+Over budget: cut background prose first, then examples, then convention lines that only *probably* pass the test.

package/skills/agents-md-generator/templates/agents-md.md

@@ -0,0 +1,48 @@
+# AGENTS.md — {project name}
+
+> {One line: what an agent needs to know it is working on.}
+
+## Repo in one paragraph
+
+{What this is, what it produces, and the one structural fact an agent must hold. 3–5 lines.}
+
+## Commands
+
+<!-- Every row traces to a file. No row may be inferred from ecosystem convention. -->
+
+| Task | Command | Source |
+|---|---|---|
+| Install | `{cmd}` | `{file}` → `{key}` |
+| Build | `{cmd}` | `{file}` → `{key}` |
+| Test | `{cmd}` *or* `[missing: no test command in CI or manifests]` | `{file}` → `{key}` |
+| Lint | `{cmd}` | `{file}` → `{key}` |
+| Run locally | `{cmd}` | `{file}` → `{key}` |
+
+{Drop the Source column from the final file if it crowds the budget — but only after every row has been verified with it present.}
+
+## File placement
+
+| Kind | Where |
+|---|---|
+| {thing} | `{path}` |
+
+## Conventions
+
+<!-- Each line must pass: without it, would a competent agent do the wrong thing? -->
+
+- **{Rule stated as a rule.}** {One clause of why, only if the why changes how it is applied.}
+
+## Do not
+
+- {Path, command, or action that must never happen unattended — concrete.}
+- {Generated artifacts that must not be hand-edited, and the command that regenerates them.}
+
+## Pointers
+
+- {Deeper doc}: `{path}`
+- {Architecture / design}: `{path}`
+
+<!--
+Line budget: 150. Provenance for every command was verified at generation time.
+Commands marked [missing] are findings, not omissions — the repo has no such command.
+-->