skilldrop-cli 0.8.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 |

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.8.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.
+-->