# skilldrop

[![npm](https://img.shields.io/npm/v/skilldrop-cli)](https://www.npmjs.com/package/skilldrop-cli)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**[Browse the catalogue →](https://sananthanarayan.github.io/skilldrop/)** — all 57 skills, filterable by outcome, pack, tag, and model tier.

**57 portable AI-agent skills for the deliverables knowledge workers actually ship** — diagrams, design docs, ADRs, PRDs, runbooks, decks, decision logs, threat models, adversarial reviews — installable into **Claude Code**, **Cursor**, **Kiro**, **Codex**, **GitHub Copilot**, and any AI tool that accepts custom instructions, one skill or one role-based pack at a time:

```bash
npx skilldrop-cli install --pack product-manager     # or: solution-architect, dev-team,
npx skilldrop-cli list                               #     sre-oncall, stakeholder-comms, ai-engineering
```

Originally scoped to solution architects, now broadly useful to PMs, founders, consultants, engineering leaders, exec assistants — anyone who turns ideas into stakeholder-ready artifacts.

Every skill is a plain `SKILL.md` folder — the [**Agent Skills open standard**](https://agentskills.io) Anthropic ratified — so the same folder runs unchanged in Claude.ai, Claude Code, the Claude Agent SDK, Cursor, Kiro, Codex, Copilot, Antigravity, and anything else that reads the format. Portable by construction: no runtime, no platform, no lock-in.

**Why skilldrop over heavier agent platforms:** every skill is a plain folder (`SKILL.md` + `manifest.json` + supporting files) and installs by *copy, never transformation* — what runs in your IDE is byte-identical to what's reviewed in this repo. The flat layout doubles as an open catalog contract: [any repo shaped like this one](#third-party-catalogs--publish-your-own-skills-through-the-same-cli) is installable through the same CLI. Skills are *opinionated* — each ships a quality bar, anti-patterns, and acceptance evals, so the output is an artifact, not a vibe.

## How skilldrop works

skilldrop runs two value streams, and **nothing comes out of either until it passes a review gate.** Both diagrams render on GitHub; the Mermaid sources live in [`docs/`](docs/) for easy re-rendering.

### Knowledge-work pipeline

Raw input becomes a stakeholder-ready artifact — and loops back through review until it's approved.

```mermaid
%%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
flowchart LR
    classDef input  fill:#FFF4E0,stroke:#E8A93B,stroke-width:2px,color:#7A4E00,font-weight:bold;
    classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
    classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
    classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;

    IN(["Raw input<br/>notes · ticket · transcript"]):::input
    brief["Structure the brief"]:::gen
    gens["Draft the artifact"]:::gen
    crit["Review and refine"]:::review
    ART(["Stakeholder-ready<br/>artifact"]):::ship

    IN --> brief --> gens --> crit
    crit -- "revise" --> brief
    crit == "approved" ==> ART
```

### Code: implement and verify

A feature spec becomes shippable code through a self-correcting loop — generate, adversarially challenge, close the gaps, re-check — until the review is clean or a 3-round cap is hit. This is the [`feature-implement-loop`](skills/feature-implement-loop/SKILL.md) skill.

```mermaid
%%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
flowchart LR
    classDef input  fill:#FFF4E0,stroke:#E8A93B,stroke-width:2px,color:#7A4E00,font-weight:bold;
    classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
    classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
    classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
    classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;

    IN(["Feature / story<br/>description + acceptance criteria"]):::input
    gC["Write and update<br/>code and tests"]:::gen
    revC["Challenge the code"]:::review
    gate{"Gaps found?"}:::gate
    SHIP(["Feature ready<br/>to be shipped"]):::ship

    IN --> gC --> revC --> gate
    gate -- "yes (up to 3 rounds)" --> gC
    gate == "no" ==> SHIP
```

## Skills in this repo

### Pipeline glue

| Skill | What it does |
|---|---|
| [`brief-intake`](skills/brief-intake/SKILL.md) | Upstream collector. Takes raw mess — a Slack thread, meeting transcript, ticket, email chain, paragraph of notes — and emits a structured brief shaped for whichever downstream skill comes next (ADR, design doc, runbook, exec summary, deck, comparison matrix, decision log). Every field is tagged `[explicit] / [implied] / [inferred] / [missing]` with verbatim quotes from the source. |
| [`doc-critique`](skills/doc-critique/SKILL.md) | Counterpart reviewer. Takes an existing doc (ADR, design doc, runbook, exec summary, comparison matrix, deck, decision log) and produces a structured critique against the same rubrics the generators enforce — verdict + severity-tagged findings (blocker / major / minor / nit) with quoted evidence and concrete fixes, plus a "what's working" section. |
| [`output-hygiene`](skills/output-hygiene/SKILL.md) | Pre-ship surface pass. Runs a stdlib-only script over agent-written text to find what the machine put there — invisible Unicode, non-breaking spaces, homoglyphs, harness-added provenance trailers, trailing chat closers — reporting each with its codepoint and line, then sweeps the prose for the tells a script cannot see and quotes every one with a rewrite. Separates what is safe to auto-apply from what needs a decision, and holds the provenance class where an academic, employer, or contribution policy requires disclosure. |

### Planning & delivery

Skills for the SDLC steps around the code itself — turning raw requirements into shippable, testable units of work and tracking them to release. (`feature-implement-loop` under Dev workflow is the natural downstream of these.)

| Skill | What it does |
|---|---|
| [`capacity-cost-model`](skills/capacity-cost-model/SKILL.md) | Build a capacity and cost model for a service or feature — sized from a **demand driver and its growth curve**, never from a chosen instance count. Everything expressed as **unit economics** (cost per request / tenant / GB, so it projects and optimizes); peak-vs-average and headroom written as explicit money-vs-incident decisions; cost at **1×/3×/10× with the scaling cliffs named** (tier jumps, cross-AZ egress, single-node→sharded) instead of a linear extrapolation that hides them; the **forgotten line items** checklisted (egress, observability ingestion, backups×retention×copies, non-prod, always-on NAT/LB) because their absence is what makes a model land 40% low; cost-drivers ranked; ranges not false precision; and a unit-cost-at-scale check that flags rising per-unit cost as an architecture problem. |
| [`business-case`](skills/business-case/SKILL.md) | Business case for a build/buy/defer investment decision, written so a sponsor can approve, challenge, or kill it on its merits. **Option 0 (do nothing) always present and costed**; every benefit is a re-runnable calculation with sourced inputs and a confidence tag (adjective benefits don't survive); all three cost layers per option — build, run (the year-2+ layer where cases go to die), and opportunity with the displaced work named; **ranges instead of false precision** ("327% ROI" from three guesses fails the doc); the **flip-assumption** identified with a de-risking step when confidence is low; a singular committal recommendation that states the runner-up's best argument fairly; and the ask in the first 40 words. |
| [`requirements-interview`](skills/requirements-interview/SKILL.md) | Per-stakeholder interview kits for feature discovery — sponsor, end users, ops/support, security/legal, finance — built only for stakeholders holding *open* unknowns. ≤7 questions per kit ranked by design impact, each annotated with the decision it informs and how the answer moves the design; problems-and-the-past phrasing only ("the last time", never "would you use…"); a mandatory **kill-question** per script with what a kill-answer looks like; and an assumptions-to-validate ledger where every assumption has a falsification condition (or gets flagged as needing data/prototype instead). Notes flow to `brief-intake` → `prd-draft`. |
| [`prd-draft`](skills/prd-draft/SKILL.md) | Draft a Product Requirements Document from a feature idea or `brief-intake` output — the missing link before design starts. Problem statement with **zero solution nouns** (tested: could it justify a different solution than the one in everyone's head?), personas specific enough to find one, a measurable "we'll know it worked when" line per goal, testable MoSCoW-prioritized requirements with a mandatory Won't-have list, **minimum 3 non-goals** (the scope-creep firewall), open questions with owners and dates, and every claim tagged `[reported by …]` / `[data: …]` / `[assumption]`. Sized for a 30-minute read; hands off to `user-story-splitter`, `nfr-spec`, `success-metrics`, and `design-doc`. |
| [`nfr-spec`](skills/nfr-spec/SKILL.md) | Sweep a feature through the full non-functional-requirements catalog — performance, throughput, availability/SLO, durability/DR, privacy/retention, accessibility, i18n, observability, operability, compatibility, cost. Every category lands in exactly one of three states: measurable target with a verification method, explicit n/a with a reason, or archetype default tagged `[assumption]` — silence is forbidden, and the output ledger proves the sweep happened. Targets are calibrated by system archetype and the "what happens if it's down for an hour" answer (anti-five-nines-cargo-cult); retention/deletion is first-class per data class; observability is written as 3am questions, not tool names. Feeds `design-doc`, `test-plan-generator`, and `threat-model`. |
| [`success-metrics`](skills/success-metrics/SKILL.md) | Define how a feature's success will be measured *before* it's built. Exactly one primary metric — an outcome, not an output or vanity count — with baseline, target, and timeframe (no baseline? measuring it becomes milestone 1); leading indicators for steering; guardrails with current values and alert thresholds; a **counter-metric** naming how the primary could be gamed and what catches it; an instrumentation plan where every metric maps to a named event marked exists/must-build (must-build = launch blocker, not fast-follow); and a **pre-committed, action-shaped decision rule** so a missed target triggers an agreed action instead of a "directionally positive" debate. |
| [`user-story-splitter`](skills/user-story-splitter/SKILL.md) | Split an epic, feature request, or PRD chunk into independently shippable vertical-slice user stories — SPIDR slicing patterns, walking-skeleton-first build order, 3–7 Gherkin acceptance criteria per story (always including an edge case), tagged `[assumption]`s, and an explicit "out of scope / not covered" ledger so nothing silently disappears. Each emitted story is shaped to hand straight to `feature-implement-loop`. |
| [`test-plan-generator`](skills/test-plan-generator/SKILL.md) | Generate a risk-based test plan for a feature, PR, or release. Risks ranked likelihood × impact before any test case is written (effort tracks priority); each case pushed to the lowest pyramid level that catches the failure (unit > integration > e2e, with e2e placement justified); every acceptance criterion mapped in a coverage table; edge-case taxonomy sweep (boundaries, idempotency, concurrency, dependency failure, timezones, …); observable entry/exit criteria; and a mandatory "Not tested — accepted risks" section. Takes `user-story-splitter` output, a diff/PR, or a prose brief. |
| [`release-notes`](skills/release-notes/SKILL.md) | Turn git history between two refs (default: last tag → HEAD) into two artifacts: customer-facing release notes rewritten in reader benefits — no commit-speak, no ticket IDs, no "various improvements" — and an internal Keep-a-Changelog version with a commit hash on every line. Breaking changes hoisted to the top of both with an "Action required" line (detected via `!:` markers, removed public API, migration files, major bumps); internal noise (refactors, CI, deps) never leaks into customer notes; vague commits land in a "Needs review" list instead of being guessed at. |
| [`bug-triage`](skills/bug-triage/SKILL.md) | Turn a vague bug report ("it's broken on mobile sometimes") into a ticket an engineer can start without contacting the reporter: searchable symptom-plus-condition title, numbered repro steps from a clean state (or an explicit "no repro yet" with the exact diagnostics to collect), expected-vs-actual with the verbatim error string, every claim tagged `[reported]` / `[verified]` / `[assumption]`, severity and priority judged independently (S4/P1 is a legitimate combination), ≤3 hypotheses each with a 5-minute check, and duplicate-search hints. One bug per ticket — multi-symptom reports get split. |
| [`migration-plan`](skills/migration-plan/SKILL.md) | Phased migration/rollout plan (schema change with live backfill, API version, datastore/auth/platform swap) built on the parallel-change pattern: expand → migrate → contract. One change per phase (a failed phase implicates exactly one thing); every phase carries an observable gate with bake time, a tested rollback with an explicit data story, and a blast radius; at most one **named point of no return**; backfill specified idempotent + resumable + rate-limited with 3-depth parity checks; dual-write requires a named reconciler; the contract phase gets a date and an owner so "we'll remove the old path later" actually happens. |

### Product strategy

Skills for the direction-setting layer above any single feature — testing whether a product idea deserves a team, analyzing a market position, and turning strategy into aligned goals. (`business-case` under Planning & delivery is the natural costed follow-on.)

| Skill | What it does |
|---|---|
| [`prfaq`](skills/prfaq/SKILL.md) | Write an Amazon-style PR/FAQ — the launch press release for a product that doesn't exist yet, plus customer and internal FAQs that force the hard questions before engineering starts. Problem stated in the customer's words (no jargon-laundering); solution names a **mechanism**, not a category; an **adoption hypothesis** with a behavioral first-success event (never "ships to beta" — that's the team's action, not the customer's); at least one customer-FAQ answer concedes a real trade-off; the internal FAQ names the riskiest assumption, a concrete acquisition path, a success metric that counts the first-success event, and a **kill condition**. Zero spec content — hands off to `prd-draft` or `business-case` if the idea survives. |
| [`strategy-analysis`](skills/strategy-analysis/SKILL.md) | Run a strategy framework — SWOT/TOWS, Porter's Five Forces, or PESTLE — chosen to fit the question, not the request (a "SWOT" that's really "should we enter this market" gets Five Forces suggested). Every cell must be **specific, evidence-tagged, and carry a so-what** — horoscope cells ("strong team") are banned; SWOT never ships without TOWS crossings; every Five Forces rating names the mechanism (who holds the power and why). Ends with **ranked, action-shaped implications** tied to a named decision and a verdict that takes a side and states what would change it. |
| [`okr-cascade`](skills/okr-cascade/SKILL.md) | Cascade company OKRs to team level with the two things cascades usually hide: a **ranked gap registry** (objectives no team credibly owns) and a **causal metric tree** (Mermaid) connecting every team KR to the north-star via a written causal sentence. Output KRs flagged at intake ("launch v2" → what outcome does it serve?); every team KR scorable 0.0–1.0 and measurable at the team's own scope; no alignment theater (teams with no credible contribution to an objective simply don't appear under it); company OKRs kept verbatim so the roll-up stays honest. Org-level counterpart to `success-metrics`, which takes each team KR into full feature-level measurement design. |

### Dev workflow

| Skill | What it does |
|---|---|
| [`feature-implement-loop`](skills/feature-implement-loop/SKILL.md) | Implement a feature/story so it ends up *verified*, not just generated. Takes a description + acceptance criteria, writes code and tests, then runs a review panel (delegating to the `devils-advocate`, `security-reviewer`, and `code-quality` subagents in parallel where available, sweeping the lenses inline elsewhere) to find gaps — broken edge cases, baked-in assumptions, acceptance criteria with no asserting test — and re-generates to close them. Loops until the review is clean or a hard 3-round cap is hit, then reports status (`VERIFIED` / `VERIFIED WITH OPEN ITEMS` / `BLOCKED`), an acceptance-criteria coverage table, and a per-round log. The build-cycle counterpart to the artifact pipeline. |
| [`pre-merge-review`](skills/pre-merge-review/SKILL.md) | Gate an existing change before merge with **one** command that fires the whole review fleet: a deterministic **mechanical gate** (`scripts/gate.py` runs the project's lint + typecheck + tests; its exit code decides — un-bypassable) **and** the three-reviewer panel — `devils-advocate` (correctness), `security-reviewer` (exploitability), `code-quality` (craft) — dispatched in parallel, then a single **READY / NOT READY** verdict (READY only when the gate is green *and* no blocker/major stands). Where `feature-implement-loop` *generates* and loops, this *judges* a diff you already have; design disagreements escalate to `council-review`. |
| [`devils-advocate`](skills/devils-advocate/SKILL.md) | Adversarial review of *just-generated* code, run right after an agent (or human) declares a feature done. Sweeps four lenses — edge cases the first pass missed, assumptions baked in that won't survive 6 months, what a staff engineer would push back on in review (concurrency, error handling, security, observability, blast radius), and test-coverage gaps. Produces severity-tagged findings (blocker / major / minor / nit) with file:line evidence, reproducible scenarios, and concrete fixes — plus a "what's solid" section. The code counterpart to `doc-critique`. |
| [`council-review`](skills/council-review/SKILL.md) | The "Claude Council." Convenes five distinct senior-engineer personas — 🏛 Architect, 🔒 Security, 🛠 Operator/SRE, ⚖️ Pragmatist, 👤 User-Advocate (plus optional bench seats: Performance, Cost, Data & Migration, Accessibility, Compliance) — to deliberate a decision, design, or code change. Each seat takes an independent stance (🟢 support / 🟡 conditions / 🔴 oppose / ⚪ abstain) with evidence; the genuine disagreements surface as named **cruxes**; a **Chair** issues a reconciled verdict (PROCEED / WITH CONDITIONS / REVISE / RECONSIDER / SPLIT) that names the tradeoff chosen, records dissent, and states what would change the decision. Where `devils-advocate` is one voice, the council is many that can disagree. Use for architecture decisions, risky changes before merge, RFC scrutiny, "should we adopt X?", or a pre-mortem. |
| [`threat-model`](skills/threat-model/SKILL.md) | STRIDE threat model from a design doc, architecture description, or `reverse-architecture` output — *before* the code exists. Establishes assets / entry points / trust boundaries first, runs STRIDE per boundary crossing, and writes every threat as a concrete actor → path → result scenario (severity 🟥/🟧/🟨/⚪ calibrated to *this* system's assets, not CVSS theater). Credits existing mitigations as verified-vs-assumed, attaches a verification step to every recommendation, and forces the two classic blind-spot sweeps: authz (tenant→tenant, authn ≠ authz) and insider/compromised-credential. Design-phase counterpart to `devils-advocate`. |
| [`accessibility-audit`](skills/accessibility-audit/SKILL.md) | Adversarial WCAG 2.2 AA audit of a UI — component code, page markup, screenshot, or a described flow. The UI counterpart to `devils-advocate`: every finding cites a **specific success criterion** (number + name + level), names the **user group and assistive tech it blocks** (no victim, no finding), is severity-tagged by task-completion impact (🟥 blocker → ⚪ nit), and carries a concrete fix. Computes real contrast ratios (not eyeballing), sweeps the high-yield checks scanners miss (focus order, name/role/value, alt-text *quality*, error recovery, reflow, target size), tags each finding `[auto]` vs `[manual]` so CI-gateable issues are split from the human-only ones, and states the input's coverage limits — a screenshot audit never claims keyboard operability passes. Ships the WCAG catalog and a worked example. |
| [`sonar-onboard`](skills/sonar-onboard/SKILL.md) | One-shot scaffold to make a repo Sonar-compliant. Supports both **SonarQube server** (self-hosted) and **SonarCloud** (SaaS) — user picks at setup. Emits `sonar-project.properties` with language-detected source/test/coverage paths, a GitHub Actions workflow that runs the scanner on push + PR and blocks merge on quality-gate failure, and a README snippet documenting the gate. |
| [`sonar-review`](skills/sonar-review/SKILL.md) | Per-change Sonar compliance review. Runs the scanner against the current branch, fetches the quality-gate verdict + issues + security hotspots from the Sonar API, and produces a structured markdown report scoped to changed files: gate PASS/FAIL on top, then severity-tagged findings (🟥 blocker / 🟧 critical / 🟨 major / ⚪ minor) grouped into five lenses (bugs, vulnerabilities, security hotspots, code smells, coverage + duplication), each with file:line, the Sonar rule ID, why it matters, and a concrete fix. Auto-detects server vs cloud from `sonar-project.properties`. Sister skill to `devils-advocate`. |

### Diagrams

| Skill | What it does |
|---|---|
| [`architecture-diagrams`](skills/architecture-diagrams/SKILL.md) | Turn a written description of a system into a renderable Mermaid, PlantUML, or C4 diagram. Supports AWS / Azure / GCP cloud shapes, sequence flows, container diagrams, and ER models. |
| [`reverse-architecture`](skills/reverse-architecture/SKILL.md) | Reverse-engineer a system's "as-is" architecture from existing code, IaC (Terraform / CloudFormation / CDK / Pulumi / Bicep), Kubernetes manifests, docker-compose, package manifests, database schema, or OpenAPI. Emits a structured node/edge extraction, a written description suitable for `architecture-diagrams`, and a first-draft Mermaid / C4 diagram with every node tied to a source-of-truth file path. |
| [`figma-diagrams`](skills/figma-diagrams/SKILL.md) | Read structure from existing Figma/FigJam files and produce FigJam-importable diagram specs (and comments) via the Figma REST API. Useful when your final deliverable lives in Figma. |
| [`user-journey-map`](skills/user-journey-map/SKILL.md) | Map one persona's end-to-end journey toward one outcome — 3–6 goal-phase stages (never one-per-screen), each with actions / reasoned emotion scores / pains / **outcome-shaped opportunities** (no solutioning — "add SSO" belongs downstream), rendered as a Mermaid `journey` emotion arc. Declares its **evidence level** up front (`[observational]` / `[survey/analytics]` / `[assumption-based]`) so a hypothesis never masquerades as research; marks the steepest dips, the peak, and the *ending* emotion (peak-end rule); and ranks opportunities down to **1–2 named improvement targets** instead of an unranked pain inventory. Hands committed targets to `prd-draft` / `user-story-splitter` and measurement to `success-metrics`. |

### Documentation

| Skill | What it does |
|---|---|
| [`adr-generator`](skills/adr-generator/SKILL.md) | Generate an Architecture Decision Record in MADR or Nygard format from a context-decision-consequences brief, with sensible numbering and filename. |
| [`design-doc`](skills/design-doc/SKILL.md) | Generate a Google-style engineering design doc (problem → goals/non-goals → alternatives → proposal → risks → rollout) from a feature brief. |
| [`runbook-generator`](skills/runbook-generator/SKILL.md) | Generate an operational runbook for a service — deploy/rollback, top 5 incident playbooks, SLOs, on-call escalation, dependencies. |
| [`observability-plan`](skills/observability-plan/SKILL.md) | Design the telemetry that makes a service detectable-before-users-complain and debuggable-at-3am. SLIs defined from **user journeys** (good/valid events), not resource graphs — latency SLIs as threshold counts at a percentile, never averages; SLOs with an **error budget in human terms and a spend policy** (what freezes when it's gone); **symptom-based, multi-window burn-rate alerting** where a page means a human must act now and every page is runbook-linked (the alert-fatigue fix); the three pillars split by purpose (metrics for SLOs/alerts with bounded cardinality, structured sampled logs for debugging, tail-sampled traces for cross-service attribution); and a **cardinality + cost budget** so observability doesn't become the surprise invoice. Expands `nfr-spec`'s observability row; feeds `runbook-generator`, `incident-comms`, `postmortem-generator`. |
| [`postmortem-generator`](skills/postmortem-generator/SKILL.md) | Generate a blameless incident postmortem from raw response material (Slack scrollback, pager timeline, notes). Quantified impact table (numbers or `[missing]` — never "significant impact"); UTC timeline with computed detection and mitigation gaps; 2+ contributing factors with "human error" structurally banned; mandatory what-went-well / poorly / **where-we-got-lucky** lists; ≤8 action items each with owner role, prevent/detect/mitigate class, and a verifiable done-condition; ends with paste-ready runbook deltas for `runbook-generator`. |
| [`guide-builder`](skills/guide-builder/SKILL.md) | Turn raw notes or a spec into an easy-to-follow guide, auto-styled to the content: a setup/quickstart (prerequisites → steps → verify → troubleshooting), a design walkthrough (mental model → flow → key decisions → where the code lives), or an API/event-schema reference (typed contracts + example payloads + error catalog). Distinct from `runbook-generator` (SRE/on-call) and `design-doc` (proposal for review). |
| [`api-contract-draft`](skills/api-contract-draft/SKILL.md) | Draft an OpenAPI 3.1 contract from a feature brief, *before* the code — resource-oriented paths (plural nouns, no RPC verbs), full RFC 9457 error catalog with machine-readable codes per operation, cursor pagination / `Idempotency-Key` / URL versioning decided at draft time instead of retrofitted, production-realistic examples on every operation, and typing rules that ban the classic regrets (float money, naked timestamps, unbounded strings). Emits a **decisions log** alongside the YAML so reviewers argue choices, not line numbers. Handles event/webhook contracts (AsyncAPI-shaped) with the same rigor. Designing new contracts only — documenting an existing API is `guide-builder`'s job. |
| [`db-schema-design`](skills/db-schema-design/SKILL.md) | Design a database schema **from the queries backward** — the access patterns (frequency, selectivity, consistency) come before any table is drawn. Paradigm chosen with a reason tied to those patterns (relational is the default and needs none; every move past it justifies itself); keys designed from queries (surrogate PK by default, NoSQL partition+sort key to avoid hot partitions, no random UUIDv4 as a clustered key); 3NF then denormalize only for a named hot read *with* its sync obligation; indexes mapped one-to-one to real queries (composite order = equality→range→sort); money/time/enum types right at the schema; explicit multitenancy and unbounded-growth-table decisions; and a **verification table proving every access pattern has a supporting path**, full scans flagged. Distinct from `data-contract` (published-dataset guarantee) and `api-contract-draft` (sync interface); hands evolution to `migration-plan`. |
| [`data-contract`](skills/data-contract/SKILL.md) | Draft a data contract for a dataset, table, or event stream others depend on — the data-engineering counterpart to `api-contract-draft`. Schema specified with **per-field semantics and units** (the cents-vs-dollars, UTC-vs-local, gross-vs-net firewall), measurable quality SLAs across freshness / completeness / validity / uniqueness / distribution — each with a threshold, a check, and a **breach action** — a schema-evolution policy that names the silent killer (changing a field's *meaning* under a stable name/type is breaking, and no validator catches it), enumerated consumers (so "breaking" is defined and notices have an address), a named owner, and per-field PII classification. Marks aspirational-vs-met SLAs honestly on existing assets. |
| [`tech-comparison-matrix`](skills/tech-comparison-matrix/SKILL.md) | Produce a weighted comparison matrix for a tech-selection question (e.g. "Postgres vs DynamoDB") with criteria, weights, scores, and a recommendation. |

### Agent engineering

Designing the agentic systems themselves — the loops, orchestrations, and budgets that turn "prompting an agent" into infrastructure a team can run unattended. (`feature-implement-loop` under Dev workflow is the in-repo worked example of a supervised loop; `llm-eval-harness` below builds the verifier's quality gate.)

| Skill | What it does |
|---|---|
| [`agent-loop-design`](skills/agent-loop-design/SKILL.md) | Design a supervised agent loop as an implementable **loop spec**: a strict generate→verify→gate state machine (no mushy "reflect" states), an **observable done-condition** (never "output looks good"), verifier structurally ≠ generator (self-grading inflates), **both caps as numbers** (revision cap defaulting to 3, budget cap per run), human gates at every irreversible action with **decision-shaped digests** (never transcripts), findings flowing into the next round (else it's retry, not iteration), three specified failure routes (cap-hit / can't-judge / systemic early-stop), and a telemetry row so the loop's degradation shows up before its output does. |
| [`subagent-design`](skills/subagent-design/SKILL.md) | Decompose a task into orchestrator + subagents — starting from **"the default answer is one agent"**: fan-out must earn itself via context separation, independence, or role conflict, or the plan says so. One-mission **role cards** (typed output contracts, explicit context-isolation lines, least-privilege tools, structured failure behavior), topology chosen with the reason attached (pipeline default; barriers only for named cross-item dependencies; judge panels with a vote rule), depth capped at one level, an **adversarial verification stage that is never a generator**, and a budget line per fleet. |
| [`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 |
|---|---|
| [`agent-adoption-stage`](skills/agent-adoption-stage/SKILL.md) | Place an engineering team on the agentic-coding ladder — **0 gated → 1 assisted (~1 agent) → 2 parallel (~10) → 3 supervised autonomy (~100) → 4 intent-steered (~1000+)** — from observables (agents in flight, who writes the code, what still gets reviewed), never from licence counts or ambition. The load-bearing idea is that **the bottleneck moves**: your attention → review throughput → trust in the loop → finding the work to automate, so the fix that unlocked the last step does nothing for the next. Forces **exactly one stage** and **exactly one unlock**, names the guardrail to *retire* (reading every diff is right at stage 1 and arithmetically impossible at stage 3), and routes each unlock to the skill that implements it (`pre-merge-review`, `agent-loop-design`, `subagent-design`, `agent-budget`). Adapted from Boris Cherny's *Steps of AI Adoption*, stated as capabilities rather than products so it survives the next vendor release. |
| [`ai-readiness-assessment`](skills/ai-readiness-assessment/SKILL.md) | Score readiness to adopt AI across **six fixed dimensions** — data, tooling, skills, governance, process, culture — each 0–4 with a **one-line evidence reference**, or `[insufficient evidence]` rather than a guessed middle number. Gaps are ranked by **what blocks first**, not by lowest score, with the dependency named ("Skills can't move until Tooling ≥ 2"), and each carries a first action and an owner *role*. Ends with a posture sentence that takes a position and names what would change it — never a bare maturity label, because "you are Level 2 of 5" is not something a leader can fund. |
| [`ai-use-case-triage`](skills/ai-use-case-triage/SKILL.md) | Rank candidate AI use cases on value × feasibility × risk with the **weights shown** (default 40/35/25). Each candidate is restated as *a workflow and a person*, never a technology; feasibility asks whether the output can be **verified before it matters**, not whether a model can produce it. Produces a recommended first slice with an **observable kill condition** and a time box, plus a mandatory **not-yet list** where every rejection carries the condition that would promote it. A portfolio with no rejections hasn't triaged anything. |
| [`ai-adoption-rollout`](skills/ai-adoption-rollout/SKILL.md) | Plan the **human** rollout (the counterpart to `migration-plan`'s technical one) — cohorts smallest-first with a reason each is next, per-cohort hands-on enablement built from what the pilot actually got stuck on, champions as roles **with protected hours**, and an adoption **gate per wave** (observable + threshold + bake time + rollback). The comms plan must state explicitly **what will not change** about headcount and evaluation; silence there is read as bad news and is the biggest driver of quiet non-adoption. Licences activated is not adoption. |
| [`ai-usage-policy`](skills/ai-usage-policy/SKILL.md) | Draft the organisation-wide acceptable-use policy — **three** data tiers (five aren't memorable at the moment of pasting) with concrete examples from *this* org, permitted/prohibited uses stated as behaviours, and a human-review matrix keyed to **consequence** rather than to model names that age out in months. Every prohibition names a permitted alternative, because a ban with no sanctioned path moves the work to personal accounts where you can't see it — and there's always an exception route with a turnaround time. |
| [`ai-usage-report`](skills/ai-usage-report/SKILL.md) | Turn a CSV/JSONL of AI usage events (exported from an MCP server or other telemetry source) into a per-user, team-rollup, or effectiveness-focused report. Surfaces volume, breadth, session depth, and — where the data supports it — whether AI outputs were actually consumed in shipped artifacts vs generated and discarded (the "AI theater" question). Refuses to generate an aggregate rollup for teams smaller than 5 to preserve anonymity. |
| [`llm-eval-harness`](skills/llm-eval-harness/SKILL.md) | Design the **dev-loop quality gate** for an LLM-powered feature (prompt, RAG, agent, classifier) — so prompt and model changes ship on numbers, not vibes. A versioned golden set in three deliberate buckets (representative from real logs, adversarial/edge, and regression cases frozen from every past failure); the **cheapest adequate grading method per case** (programmatic → structured assertions → LLM-as-judge only when quality is genuinely subjective, and then validated against human labels with bias controls); a metric matched to the task with **both gates set before the first run** (no-regression + critical-subset-at-100%); a failure taxonomy that points iteration at the biggest bucket; and cost/latency tracked beside quality. Enforces the held-out split and the no-tuning-on-test rule. Provider-neutral. |

### Stakeholder communication

| Skill | What it does |
|---|---|
| [`audience-profile`](skills/audience-profile/SKILL.md) | Translate an audience type (exec, board, technical, sales, investor, internal, partner, customer) into structural rules — slide count, density, tone, must-have sections. Reusable input for the next three skills. |
| [`slide-outliner`](skills/slide-outliner/SKILL.md) | Outline an architecture-review or pitch deck — slide titles, key points, and speaker notes — sized to a target time budget. Doesn't generate PPTX. |
| [`deck-builder`](skills/deck-builder/SKILL.md) | Generate a real PowerPoint (`.pptx`) file from content + audience + color palette. Uses `python-pptx`; supports 7 layout types and audience-tuned density. Pairs naturally with `audience-profile` + `slide-outliner`. |
| [`exec-summary`](skills/exec-summary/SKILL.md) | Compress a long technical document into a one-page executive summary structured around an Ask, business impact, cost/timeline, risks, and what you need from the audience. |
| [`decision-log`](skills/decision-log/SKILL.md) | Extract decisions, action items, owners, and due dates from meeting notes, Slack threads, or transcripts into a structured log with source attribution. |
| [`incident-comms`](skills/incident-comms/SKILL.md) | Draft the messages you send *while an incident is still burning* — audience-segmented into customer status-page posts, internal stakeholder updates that arm the relayer, and three-sentence exec briefs (business impact + the ask). Every message leads with reader-facing impact (not internal symptom), uses the precise status vocabulary (investigating / identified / monitoring / resolved), commits only to the **next-update time** (never a fix ETA or speculative cause you'd have to retract), and stays blameless and screenshot-safe. Acknowledge → update-on-committed-cadence → verified resolve. Completes the operate triad with `runbook-generator` (how to fix) and `postmortem-generator` (what to say after). |

## What's in a skill

Every skill folder follows the same layout, so installation is the same anywhere:

```
skills/<skill-name>/
├── SKILL.md              # The instructions the AI agent reads — entry point
├── manifest.json         # Name, description, version, declared deps, required env vars
├── requirements.txt      # (optional) Python deps if the skill has scripts
├── reference.md          # (optional) Long-form reference material
├── examples/             # (optional) Worked examples the agent can study
├── templates/            # (optional) Starter snippets the agent can copy from
├── evals/                # (optional) Acceptance checks — evals.json (prompt + assertions) + eval_queries.json (trigger phrases)
└── scripts/              # (optional) Executable helpers the agent invokes
```

The `manifest.json` is the canonical machine-readable summary: its `deps` block lists `pip` / `npm` packages, and `env.required` lists env vars that must be set before the skill works. Its `related` block lists the sibling skills this one hands off to, builds on, or names as alternatives — the companions to install if you want the pipelines to work end-to-end. Its `model` block declares the cost-effective model tier for the skill (see below).

## Cost-aware model routing (provider-neutral)

Different skills need different horsepower — `decision-log` is mechanical extraction, `devils-advocate` is adversarial reasoning. Running both on the same frontier model wastes money on the cheap one; running both cheap loses the hard one. So each skill carries an **abstract tier** describing the *task*, decided once:

| Tier | For |
|---|---|
| 🟢 `light` | Mechanical mapping / extraction |
| 🔵 `standard` | Most generation (the default) |
| 🟣 `heavy` | Adversarial reasoning / weighted judgment (never downgraded) |

The tier is **not tied to Claude.** A `providers` map in [`model-routing.json`](model-routing.json) resolves each tier to a concrete model for whatever tool you use — Claude Code, Cursor, Codex, Kiro, or anything else. Set `active_provider` to your tool and fill in its three model names (Claude Code ships filled in; the rest are templates). The same routing decisions then work everywhere.

The tier lives in each skill's `manifest.json` (`model` block, travels with the skill) and in `model-routing.json` (the source of truth). [`MODEL-ROUTING.md`](MODEL-ROUTING.md) is the human-readable table, the provider setup, and the mechanical escalation rules (escalate on large/ambiguous input; honor explicit user model choice).

**Three ways to use it:**

- **Manual (any tool):** look up the skill's tier in [`MODEL-ROUTING.md`](MODEL-ROUTING.md) → look up your tool's model for that tier → set it → invoke the skill.
- **Pure-rules CLI (any tool, no API key, no network):** [`route.py`](route.py) decides the tier deterministically from keyword + length signals with transparent, tunable weights, and prints the resolved model:

  ```bash
  python3 route.py --skill devils-advocate --input diff.txt
  git diff | python3 route.py --skill sonar-review --files 12 --json
  ```

- **Automated agent (Claude Code today):** the [`model-router`](.claude/agents/model-router.md) agent — pinned to the lightest model so routing is nearly free — runs `route.py`, resolves your active provider's model, and runs the skill on a subagent at that model:

  > Use the model-router agent to run `decision-log` on these meeting notes: …

  Other tools read the **same table** / call the **same `route.py`**, so routing decisions are identical everywhere.

Why not have an LLM pick the model live on every call? Because that pays tokens and latency *every time* to answer a question whose answer is fixed per skill. Routing is a table lookup; the model budget is spent on the work, not on deciding.

## Skill packs — install a role's toolkit in one command

Categories (above) say what a skill *is*; packs say *who needs it*. [`packs.json`](packs.json) defines six role-based bundles — packs overlap where a skill serves several roles, and every skill belongs to at least one:

| Pack | Skills | For |
|---|---|---|
| `solution-architect` | 17 | Design-phase artifacts: diagrams, ADRs, design docs, contracts, schemas, threat models, and the reviews that gate them |
| `dev-team` | 14 | Build-and-ship loop: implementation with adversarial review, test plans, triage, migrations, release notes, quality gates, pre-ship hygiene |
| `product-manager` | 13 | Direction to requirements: PR/FAQs, strategy frameworks, OKRs, PRDs, journey maps, story splitting, success measurement |
| `ai-engineering` | 12 | Build and run AI systems: agent loop design, subagent orchestration, spend budgets, eval harnesses, usage reporting, data contracts |
| `stakeholder-comms` | 9 | Non-technical audiences: audience profiling, deck outlines and real `.pptx` decks, exec summaries, decision logs, guides |
| `sre-oncall` | 5 | Operate the service: runbooks, observability design, incident comms, postmortems, capacity/cost models |

```bash
python3 pack.py                                  # list packs
python3 pack.py product-manager                  # list a pack's skills
python3 pack.py product-manager --install        # install into ~/.claude/skills/ (user scope)
python3 pack.py product-manager --install --project      # into .claude/skills/ (project scope)
python3 pack.py product-manager --install --dest .cursor/skills   # any dir, for non-Claude IDEs
```

For non-Claude IDEs, `--dest` drops the folders where your tool expects them; the per-IDE wiring steps below still apply. Packs are metadata only — skills stay in flat `skills/<name>` folders, so per-skill `cp -R` installs keep working unchanged ([RFC-0001](docs/rfcs/0001-skill-packs.md) records the design decision).

## Outcomes — browse by why you're here

Packs answer *who am I*. Outcomes answer *why did I open this*. The seven below are the nine
categories above, restated as the things people actually arrive wanting to do, and they live in
the `outcomes` block of [`packs.json`](packs.json) so the [catalogue site](https://sananthanarayan.github.io/skilldrop/)
can filter on them. Every skill belongs to at least one; `validate.py` enforces it.

| Outcome | Skills | What it covers |
|---|---|---|
| `design-the-system` | 15 | Decision records, design docs, diagrams, contracts, schemas, migration and threat models, agentic design |
| `decide-what-to-build` | 11 | Press releases, strategy frameworks, OKRs, business cases, requirements, PRDs, success metrics |
| `build-and-review-software` | 11 | Supervised implementation, review panels, test plans, triage, accessibility and static-analysis passes |
| `explain-it-to-decision-makers` | 6 | Audience profiling, deck outlines and real decks, exec summaries, decision logs, guides |
| `govern-ai-use` | 6 | Readiness, use-case triage, rollout, acceptable-use policy, adoption staging, usage reporting |
| `run-and-recover-the-service` | 5 | Runbooks, observability design, release notes, incident comms, postmortems |
| `get-a-draft-ready-to-ship` | 3 | Collect a messy input, critique the argument, strip the machine artifacts |

Outcomes are a browse aid, not an install unit — there is no `--outcome` flag. Install by skill
or by pack.

## Installing a skill into your IDE

### Quickest: the skilldrop CLI

The repo ships as the npm package **`skilldrop-cli`** (command: `skilldrop`) — a zero-dependency installer that copies skills byte-identical into your tool's location, and writes a pointer file only where the tool needs one to find them (Cursor):

```bash
npx skilldrop-cli install --pack product-manager        # Claude Code, user scope (~/.claude/skills)
npx skilldrop-cli install --pack dev-team --project     # .claude/skills — also read by GitHub Copilot CLI
npx skilldrop-cli install prfaq --ide cursor            # + writes .cursor/rules/prfaq.mdc
npx skilldrop-cli install --pack sre-oncall --ide kiro  # .kiro/skills — Kiro IDE + Kiro CLI, discovered natively
npx skilldrop-cli install adr-generator --dest .agents/skills   # Codex + Copilot CLI (see below)
npx skilldrop-cli agents                                # the reviewer subagents
npx skilldrop-cli install --agent devils-advocate       # -> ~/.claude/agents/ (RFC-0012)
npx skilldrop-cli install --panel review                # the whole review fleet: 3 subagents + the pre-merge-review orchestrator (RFC-0020)
npx skilldrop-cli outdated && npx skilldrop-cli update  # skills improve; cp -R never tells you
npx skilldrop-cli list | skilldrop info <skill> | skilldrop packs | skilldrop uninstall <skill>
npx skilldrop-cli list --json                            # machine-readable: list/info/packs/agents/outdated (RFC-0021)
```

`--with-related` also pulls each skill's companions. From a clone (or before the package is published): `node bin/skilldrop.js <same args>`. Scope and design: [RFC-0002](docs/rfcs/0002-skilldrop-cli.md), full command surface in [`docs/designs/skilldrop-cli-design.md`](docs/designs/skilldrop-cli-design.md).

### Or: the Claude Code plugin marketplace

skilldrop is also a **Claude Code plugin marketplace** — one marketplace, seven plugins, no npm step. Add it once:

```text
/plugin marketplace add sananthanarayan/skilldrop
```

Then take the whole catalogue, or just your role's pack:

```text
/plugin install skilldrop@skilldrop             # all 57 skills + 3 reviewer subagents
/plugin install solution-architect@skilldrop    # 17 skills
/plugin install dev-team@skilldrop              # 14 skills + the 3 reviewer subagents
/plugin install product-manager@skilldrop       # 13 skills
/plugin install ai-engineering@skilldrop        # 12 skills
/plugin install stakeholder-comms@skilldrop     # 9 skills
/plugin install sre-oncall@skilldrop            # 5 skills
```

Every skill then invokes as `/<plugin>:<name>` (e.g. `/skilldrop:prfaq`). The whole-catalogue plugin ships the flat `skills/` and `agents/` trees at the repo root unchanged — same copy-install premise, expressed in Claude's own plugin format.

The six **pack plugins** work differently, because a plugin's skills have to sit in a `skills/` folder inside the plugin. Rather than duplicate every skill into six directories on `main` — physical packs, which [RFC-0001](docs/rfcs/0001-skill-packs.md) rejected — the marketplace entries use Claude's `git-subdir` source to point at `packs/<name>/` on a generated [`plugins`](https://github.com/sananthanarayan/skilldrop/tree/plugins) branch, rebuilt by CI on every push to main. Nothing moves in the source tree, and you still only ever type the one `marketplace add`. A pack carries the reviewer subagents its own skills delegate to, so `dev-team` brings the review panel and `sre-oncall` does not.

`.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

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.

```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.

### Reviewer subagents

Two personas you delegate review to, rather than invoke as a skill: [`devils-advocate`](agents/devils-advocate.md) ("will this break?") and [`code-quality`](agents/code-quality.md) ("will the next engineer hate this?"). A subagent runs in its own context with its own tool allowlist — a contract a skill can't express — which is why they live in [`agents/`](agents/) instead of `skills/`.

```bash
npx skilldrop-cli agents                                    # list them
npx skilldrop-cli install --agent devils-advocate           # ~/.claude/agents/
npx skilldrop-cli install --agent code-quality --project    # .claude/agents/, shared with the repo
```

Then delegate by name: *"use the devils-advocate agent on this diff."*

Four targets, each projecting only as much as the tool's format demands:

| Target | Writes | Projection |
|---|---|---|
| *(default)* | `~/.claude/agents/<name>.md` | none — the file already is Claude Code's format |
| `--ide copilot` | `.github/agents/<name>.agent.md` | a rename |
| `--ide kiro` | `.kiro/agents/<name>.json` | generated JSON; tool names mapped to Kiro's built-ins |
| `--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.

**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.

| Agent | Reviews for | Question it answers |
|---|---|---|
| [`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).