skilldrop-cli 0.12.2 → 0.13.0

package/README.md

@@ -3,13 +3,13 @@
 [![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.
+**[Browse the catalogue →](https://sananthanarayan.github.io/skilldrop/)** — all 62 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:
+**62 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
+npx skilldrop-cli list                               #     sre-oncall, stakeholder-comms, ai-engineering, claude-api
 ```
 
 Originally scoped to solution architects, now broadly useful to PMs, founders, consultants, engineering leaders, exec assistants — anyone who turns ideas into stakeholder-ready artifacts.
@@ -308,6 +308,23 @@ Designing the agentic systems themselves — the loops, orchestrations, and budg
 | [`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. |
 
+### Claude API
+
+Skills for teams building directly on the Anthropic API — prompt caching strategy, token budgeting, eval generation for skills, and tool-use schema authoring.
+
+| Skill | What it does |
+|---|---|
+| [`prompt-caching-advisor`](skills/prompt-caching-advisor/SKILL.md) | Analyzes a prompt or conversation structure and identifies the highest-value `cache_control` breakpoints — which blocks to cache, where to place the checkpoint, and estimated hit rate. Warns when a cacheable block is below the minimum threshold (~1,024 tokens for Haiku, ~2,048 for Sonnet/Opus). Produces an annotated messages array and a one-paragraph cache strategy summary. |
+| [`token-budget-estimator`](skills/token-budget-estimator/SKILL.md) | Breaks down token usage for an agentic workflow by component — system prompt, injected context, tool definitions, tool results, context accumulation, and output — surfaces the dominant cost driver, and recommends concrete `max_tokens` controls. Covers extended thinking (`budget_tokens`) when relevant. |
+| [`eval-harness-generator`](skills/eval-harness-generator/SKILL.md) | Takes a SKILL.md and generates 8–12 eval cases (happy path, edge, anti-pattern, refusal) ready to drop into `skills/<name>/evals/cases.json`. Each case has a realistic trigger, checkable `expected_shape` criteria, and `must_not_include` guards from the skill's own quality bar. |
+| [`tool-use-schema-writer`](skills/tool-use-schema-writer/SKILL.md) | Converts a function description into a valid Anthropic `tool_use` JSON schema with typed properties, required arrays, and decision-condition descriptions. Validates that required arrays are present and enum values are described. Produces a Python `client.messages.create(tools=[...])` usage snippet. |
+
+### Skill authoring
+
+| Skill | What it does |
+|---|---|
+| [`contribution-wizard`](skills/contribution-wizard/SKILL.md) | Guides an author through creating a new skilldrop skill from scratch — single-block intake, then one response generating the manifest, SKILL.md, 8 eval cases, README row, and packs.json addition. Enforces schema compliance and names the `python3 validate.py` check as the gate before opening a PR. |
+
 ### Stakeholder communication
 
 | Skill | What it does |
@@ -381,6 +398,7 @@ Categories (above) say what a skill *is*; packs say *who needs it*. [`packs.json
 | `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 |
+| `claude-api` | 4 | Build on the Anthropic API: prompt caching strategy, token budgeting, eval generation for skills, tool-use schema writing |
 
 ```bash
 python3 pack.py                                  # list packs
@@ -448,7 +466,7 @@ skilldrop is also a **Claude Code plugin marketplace** — one marketplace, seve
 Then take the whole catalogue, or just your role's pack:
 
 ```text
-/plugin install skilldrop@skilldrop             # all 57 skills + 3 reviewer subagents
+/plugin install skilldrop@skilldrop             # all 62 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

package/bin/skilldrop.js

@@ -40,6 +40,8 @@ Usage:
   skilldrop loops [--from <src>]          loops — sequenced stages over skills (RFC-0028)
   skilldrop install <skill...>            install skills (default: Claude Code, user scope)
   skilldrop install --pack <name>         install a whole pack
+  skilldrop install --profile <name>      install a named bundle of packs, agents, and loops
+  skilldrop profiles [--from <src>]       list available profiles
   skilldrop install --all                 install every skill in the catalog
   skilldrop install --agent <name...>     install reviewer subagents (RFC-0012)
   skilldrop install --loop <name...>      install loops + the stage skills they sequence
@@ -262,6 +264,10 @@ function packsOf(cat) {
   const p = path.join(cat.dir, "packs.json");
   return fs.existsSync(p) ? readJSON(p).packs : null;
 }
+function profilesOf(cat) {
+  const p = path.join(cat.dir, "profiles.json");
+  return fs.existsSync(p) ? readJSON(p).profiles : null;
+}
 
 /* Structural gate (RFC-0003): a skill must pass before it is copied anywhere. */
 function checkSkill(cat, s) {
@@ -744,8 +750,57 @@ function installPanel(args) {
   console.log(`Codex / Antigravity multi-agent runners), and sweeps the lenses inline otherwise. Per-tool: agents/README.md.`);
 }
 
+function listProfiles(args) {
+  const cat = resolveCatalog(args.flags.from);
+  const ps = profilesOf(cat);
+  if (args.flags.json)
+    return emitJSON({
+      catalog: cat.source,
+      count: ps ? Object.keys(ps).length : 0,
+      profiles: Object.entries(ps || {}).map(([name, p]) => ({
+        name, description: p.description || null,
+        packs: p.packs || [], agents: p.agents || [], loops: p.loops || [],
+      })),
+    });
+  if (!ps) return console.log(`catalog '${cat.source}' defines no profiles.`);
+  const w = Math.max(...Object.keys(ps).map((n) => n.length));
+  for (const [n, p] of Object.entries(ps))
+    console.log(`${n.padEnd(w)}  ${p.description}`);
+  console.log("\nInstall one: skilldrop install --profile <name>");
+}
+
+function installProfile(args) {
+  const name = args.flags.profile;
+  const cat = resolveCatalog(args.flags.from);
+  const profiles = profilesOf(cat);
+  if (!profiles) die(`catalog '${cat.source}' has no profiles.json`);
+  const p = profiles[name];
+  if (!p) die(`unknown profile '${name}' — available: ${Object.keys(profiles).join(", ")}`);
+
+  console.log(`Installing profile '${name}': ${p.description}\n`);
+  const flags = Object.assign({}, args.flags);
+  delete flags.profile;
+
+  for (const pack of (p.packs || [])) {
+    console.log(`\n── pack: ${pack} ──`);
+    install({ _: [], flags: Object.assign({}, flags, { pack }) });
+  }
+  for (const loop of (p.loops || [])) {
+    if (loopsIn(cat).includes(loop)) {
+      console.log(`\n── loop: ${loop} ──`);
+      installLoops({ _: [loop], flags: Object.assign({}, flags, { loop: true }) });
+    }
+  }
+  if ((p.agents || []).length) {
+    console.log(`\n── agents: ${p.agents.join(", ")} ──`);
+    installAgents({ _: p.agents.slice(), flags: Object.assign({}, flags, { agent: true }) });
+  }
+  console.log(`\nProfile '${name}' installed.`);
+}
+
 function install(args) {
   if (args.flags.panel) return installPanel(args);
+  if (args.flags.profile) return installProfile(args);
   if (args.flags.loop) return installLoops(args);
   if (args.flags.agent) return installAgents(args);
   const cat = resolveCatalog(args.flags.from);
@@ -1192,7 +1247,7 @@ function bootstrap() {
 
 const args = parseArgs(process.argv.slice(2));
 const cmd = args._.shift();
-const commands = { list, info, packs: listPacks, agents: listAgents, loops: listLoops, install, update, outdated, uninstall, validate: validateCmd, scan, bootstrap };
+const commands = { list, info, packs: listPacks, profiles: listProfiles, agents: listAgents, loops: listLoops, install, update, outdated, uninstall, validate: validateCmd, scan, bootstrap };
 if (!cmd || cmd === "help" || args.flags.help) console.log(HELP);
 else if (commands[cmd]) commands[cmd](args);
 else die(`unknown command '${cmd}' — run: skilldrop help`);

package/model-routing.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Provider-neutral, cost-aware model routing for skilldrop skills. Skills declare an ABSTRACT tier (light/standard/heavy) describing how much reasoning the task needs. The `providers` map resolves that tier to a concrete model for whatever tool you use (Claude Code, Cursor, Codex, Kiro, ...). Set `active_provider` to your tool. Tier is decided ONCE per skill (the decision is stable), not re-derived per call — that keeps routing free. Runtime heuristics in `escalation_rules` handle the cases that actually vary.",
+  "$comment": "Provider-neutral, cost-aware model routing for skilldrop skills. Skills declare an ABSTRACT tier (light/standard/heavy) describing how much reasoning the task needs. The `providers` map resolves that tier to a concrete model for whatever tool you use (Claude Code, Cursor, Codex, Kiro, ...). Set `active_provider` to your tool. Tier is decided ONCE per skill (the decision is stable), not re-derived per call \u2014 that keeps routing free. Runtime heuristics in `escalation_rules` handle the cases that actually vary.",
   "version": "0.2.0",
   "active_provider": "claude-code",
   "tiers": {
@@ -34,7 +34,7 @@
         "standard": "<your default model>",
         "heavy": "<your most capable model>"
       },
-      "select_via": "Pick the model in the chat/composer model dropdown before invoking the skill. Cursor rules cannot switch models programmatically — this is a manual lookup.",
+      "select_via": "Pick the model in the chat/composer model dropdown before invoking the skill. Cursor rules cannot switch models programmatically \u2014 this is a manual lookup.",
       "automation": null,
       "note": "Cursor exposes whatever models your plan enables (Claude, GPT, Gemini). Fill in the three you actually use."
     },
@@ -47,7 +47,7 @@
       },
       "select_via": "Set the model via the Codex `--model` flag or its config before running the skill.",
       "automation": null,
-      "note": "Fill in with the model identifiers your Codex install accepts. Model names change — verify against `codex --help` / your config."
+      "note": "Fill in with the model identifiers your Codex install accepts. Model names change \u2014 verify against `codex --help` / your config."
     },
     "kiro": {
       "label": "Kiro",
@@ -73,7 +73,7 @@
   "escalation_rules": [
     {
       "id": "large-input",
-      "rule": "Escalate one tier (light→standard, standard→heavy) when the input the skill must reason over exceeds ~30 pages / ~20k words / ~15 source files. Large context degrades small models faster than large ones.",
+      "rule": "Escalate one tier (light\u2192standard, standard\u2192heavy) when the input the skill must reason over exceeds ~30 pages / ~20k words / ~15 source files. Large context degrades small models faster than large ones.",
       "type": "heuristic_no_llm"
     },
     {
@@ -88,7 +88,7 @@
     },
     {
       "id": "downgrade-trivial",
-      "rule": "Downgrade one tier (never below 'light', never below the skill's declared floor) when the input is tiny and templated — e.g. a one-paragraph brief into adr-generator, a 3-line note into decision-log.",
+      "rule": "Downgrade one tier (never below 'light', never below the skill's declared floor) when the input is tiny and templated \u2014 e.g. a one-paragraph brief into adr-generator, a 3-line note into decision-log.",
       "type": "heuristic_no_llm"
     },
     {
@@ -98,62 +98,253 @@
     }
   ],
   "skills": {
-    "audience-profile": { "tier": "light", "rationale": "Maps a fixed set of audience archetypes to structural rules. Lookup against a rubric, not synthesis." },
-    "decision-log": { "tier": "light", "rationale": "Extracts decisions/owners/dates from notes. Pattern extraction; escalate on long transcripts via large-input rule." },
-    "sonar-onboard": { "tier": "light", "rationale": "Scaffolds config from detected language + a template. Deterministic fill-in; little judgment." },
-    "adr-generator": { "tier": "standard", "rationale": "Structures a decision into MADR/Nygard. Some judgment on title/consequences; not adversarial." },
-    "architecture-diagrams": { "tier": "standard", "rationale": "Translates prose to diagram syntax. Correctness matters; reasoning is bounded." },
-    "brief-intake": { "tier": "standard", "rationale": "Extraction + tagging [explicit]/[implied]/[inferred]. The tagging needs care — above light, below heavy." },
-    "deck-builder": { "tier": "standard", "rationale": "Shapes content, maps a brand template's layouts, and runs a script. Judgment, not hard reasoning." },
-    "design-doc": { "tier": "standard", "rationale": "Synthesizes a design doc from a brief. Escalate to heavy via large-input or ambiguous-input when alternatives are genuinely contested." },
-    "exec-summary": { "tier": "standard", "rationale": "Compression to one page. Needs to keep the right signal; escalate on very long source docs." },
-    "figma-diagrams": { "tier": "standard", "rationale": "API calls + spec generation. Bounded transformation." },
-    "guide-builder": { "tier": "standard", "rationale": "Shapes notes into a styled guide. Generation, not adversarial review." },
-    "reverse-architecture": { "tier": "standard", "rationale": "Extracts architecture from code/IaC. Escalate to heavy on large codebases where cross-file inference is heavy." },
-    "runbook-generator": { "tier": "standard", "rationale": "Operational doc from service facts. Bounded synthesis." },
-    "slide-outliner": { "tier": "standard", "rationale": "Outlines a deck to a time budget. Structuring, not deep reasoning." },
-    "sonar-review": { "tier": "standard", "rationale": "Formats Sonar API findings into a report. The hard analysis is Sonar's; this is synthesis. Escalate on very large diffs." },
-    "ai-usage-report": { "tier": "standard", "rationale": "Tabulates telemetry into a report. Mostly mechanical, but the 'AI theater' effectiveness call needs judgment." },
-    "ai-readiness-assessment": { "tier": "standard", "rationale": "Scores six fixed dimensions against a rubric and ranks gaps by blocking order. Bounded structured judgment, not adversarial reasoning; escalate via ambiguous-input when the evidence is thin or contested." },
-    "agent-adoption-stage": { "tier": "standard", "rationale": "Places a team on a fixed 5-stage ladder from observables and routes one unlock. Bounded diagnosis against a rubric; escalate via ambiguous-input when the observables are contradictory or the distribution is heavily skewed." },
-    "ai-use-case-triage": { "tier": "standard", "rationale": "Scores candidates on weighted axes and forces a rejection list. Structured comparison with stated weights; escalate via ambiguous-input when candidates are numerous or the value data is contested." },
-    "ai-adoption-rollout": { "tier": "standard", "rationale": "Generates a phased people-rollout with gates and enablement from a stated tool and population. Structured planning against a fixed shape; escalate via ambiguous-input for large or politically contested rollouts." },
-    "ai-usage-policy": { "tier": "standard", "rationale": "Drafts a policy document against a fixed structure (tiers, behaviours, review matrix, exception route). Bounded generation; escalate via ambiguous-input where a regulatory regime is named or contested." },
-    "feature-implement-loop": { "tier": "standard", "rationale": "Code + test generation against acceptance criteria. The adversarial pass delegates to devils-advocate (heavy) where available; the loop itself is generation." },
-    "pre-merge-review": { "tier": "standard", "rationale": "Orchestration: runs a deterministic gate script, dispatches the (heavy) reviewer subagents, and renders a rule-based go/no-go. The adversarial reasoning is delegated to the panel, so the skill itself is coordination." },
-    "user-story-splitter": { "tier": "standard", "rationale": "Decomposes an epic into INVEST slices with testable ACs. Structured synthesis; escalation rules cover large or contradictory PRDs." },
-    "test-plan-generator": { "tier": "standard", "rationale": "Synthesizes a structured plan from a change description. Risk ranking needs judgment but is bounded; escalate via ambiguous-input on contested or high-stakes releases." },
-    "release-notes": { "tier": "standard", "rationale": "Classifies commits and rewrites them for a reader. The audience translation needs judgment; escalate via large-input on very long ranges." },
-    "postmortem-generator": { "tier": "standard", "rationale": "Synthesizes a structured doc from incident notes. Contributing-factor chains need judgment but are bounded; escalate via large-input on huge scrollbacks." },
-    "migration-plan": { "tier": "standard", "rationale": "Phased plan synthesis with a strong template. Ordering judgment is bounded by the expand/migrate/contract pattern; escalate via ambiguous-input on contested, high-stakes cutovers." },
-    "api-contract-draft": { "tier": "standard", "rationale": "Schema synthesis against fixed conventions. The resource modeling needs judgment; the conventions bound it. Escalate via ambiguous-input on contested multi-team contracts." },
-    "bug-triage": { "tier": "standard", "rationale": "Extraction plus judgment calls (severity vs priority, hypothesis ranking) — same shape as brief-intake: above light, below heavy." },
-    "prd-draft": { "tier": "standard", "rationale": "Synthesizes a structured requirements doc from a brief. The solution-language discipline needs care; bounded by the template. Escalate via ambiguous-input on contested scope." },
-    "nfr-spec": { "tier": "standard", "rationale": "Rubric-driven sweep with archetype defaults; the judgment is calibrating targets to business reality. Bounded by the catalog; escalate via ambiguous-input on contested SLOs." },
-    "success-metrics": { "tier": "standard", "rationale": "Structured measurement design; the primary-metric and counter-metric choices need judgment but the template bounds it. Escalate via ambiguous-input when the goal itself is contested." },
-    "requirements-interview": { "tier": "standard", "rationale": "Question banks are rubric-shaped, but ranking by design impact and deriving falsification conditions for the specific feature is synthesis — above light." },
-    "business-case": { "tier": "heavy", "rationale": "Weighted multi-option judgment with a committal recommendation — same failure mode as tech-comparison-matrix: cheaper models mis-weight costs, inflate benefits, and miss the flip-assumption. Never downgrade." },
-    "incident-comms": { "tier": "standard", "rationale": "Audience-segmented message generation under a strict don't-retract discipline. Same shape as exec-summary/audience-profile — translation and altitude, not adversarial reasoning." },
-    "data-contract": { "tier": "standard", "rationale": "Schema + SLA synthesis against fixed quality dimensions and an evolution matrix. Semantics capture needs care; bounded by the catalog. Escalate via large-input on wide schemas." },
-    "llm-eval-harness": { "tier": "standard", "rationale": "Methodology synthesis against a fixed decision tree and pitfall catalog. Grading-method and metric choices need judgment but are bounded; escalate via ambiguous-input on novel task types." },
-    "capacity-cost-model": { "tier": "standard", "rationale": "Quantitative projection from a demand model against a fixed cost catalog. Headroom and scaling-cliff judgment is bounded by the reference; escalate via ambiguous-input on novel architectures." },
-    "accessibility-audit": { "tier": "heavy", "rationale": "Adversarial review against WCAG success criteria — cheaper models fault alt-text presence over quality, under-call severity, miss focus-order/name-role-value issues, and claim AT passes from screenshots. Never downgrade." },
-    "db-schema-design": { "tier": "standard", "rationale": "Design synthesis from access patterns against a fixed paradigm/indexing/anti-pattern reference. Paradigm and denormalization judgment is bounded; escalate via ambiguous-input on contested scale/consistency tradeoffs." },
-    "observability-plan": { "tier": "standard", "rationale": "Methodology synthesis against fixed SRE practices (golden signals, burn-rate alerting, pillar split). SLO calibration needs judgment but is bounded; escalate via ambiguous-input on contested reliability targets." },
-    "council-review": { "tier": "heavy", "rationale": "Multi-perspective deliberation + weighted reconciliation across distinct expert seats. Cheaper models collapse the seats into one voice and either manufacture or miss the real cruxes. Never downgrade." },
-    "devils-advocate": { "tier": "heavy", "rationale": "Adversarial code review across four lenses. Cheaper models miss edge cases and under-call severity — the whole value is the hard thinking. Never downgrade." },
-    "output-hygiene": { "tier": "standard", "rationale": "The mechanical pass is a deterministic script; the model does bounded rewriting of flagged prose against a fixed tell list, not adversarial review." },
-    "doc-critique": { "tier": "heavy", "rationale": "Adversarial doc review against rubrics. Same as devils-advocate: the value is catching what a fast pass misses. Never downgrade." },
-    "tech-comparison-matrix": { "tier": "heavy", "rationale": "Weighted multi-criteria judgment with a recommendation. Mis-weighting is the failure mode; heavy is worth it. Never downgrade." },
-    "threat-model": { "tier": "heavy", "rationale": "Adversarial reasoning over a design — cheaper models emit checklist residue, miss authz/insider paths, and inflate severity. Never downgrade." },
-    "prfaq": { "tier": "standard", "rationale": "Synthesizes a press release and FAQs from a product concept against a fixed format. The specificity discipline needs care but the template bounds it; escalate via ambiguous-input when the concept itself is contested." },
-    "okr-cascade": { "tier": "standard", "rationale": "Structured derivation against a fixed roll-up discipline; the causal-sentence and gap judgments need care but the template bounds them. Escalate via ambiguous-input when the company objectives themselves are contested." },
-    "user-journey-map": { "tier": "standard", "rationale": "Structured synthesis into a fixed four-row stage model plus bounded ranking judgment. Escalate via ambiguous-input when the persona or outcome is contested or research inputs conflict." },
-    "strategy-analysis": { "tier": "heavy", "rationale": "Framework selection plus evidenced multi-factor judgment ending in a ranked, committal verdict. Cheaper models fill cells with generic filler, skip the TOWS crossings, and refuse to take a side. Never downgrade." },
-    "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." }
+    "audience-profile": {
+      "tier": "light",
+      "rationale": "Maps a fixed set of audience archetypes to structural rules. Lookup against a rubric, not synthesis."
+    },
+    "decision-log": {
+      "tier": "light",
+      "rationale": "Extracts decisions/owners/dates from notes. Pattern extraction; escalate on long transcripts via large-input rule."
+    },
+    "sonar-onboard": {
+      "tier": "light",
+      "rationale": "Scaffolds config from detected language + a template. Deterministic fill-in; little judgment."
+    },
+    "adr-generator": {
+      "tier": "standard",
+      "rationale": "Structures a decision into MADR/Nygard. Some judgment on title/consequences; not adversarial."
+    },
+    "architecture-diagrams": {
+      "tier": "standard",
+      "rationale": "Translates prose to diagram syntax. Correctness matters; reasoning is bounded."
+    },
+    "brief-intake": {
+      "tier": "standard",
+      "rationale": "Extraction + tagging [explicit]/[implied]/[inferred]. The tagging needs care \u2014 above light, below heavy."
+    },
+    "deck-builder": {
+      "tier": "standard",
+      "rationale": "Shapes content, maps a brand template's layouts, and runs a script. Judgment, not hard reasoning."
+    },
+    "design-doc": {
+      "tier": "standard",
+      "rationale": "Synthesizes a design doc from a brief. Escalate to heavy via large-input or ambiguous-input when alternatives are genuinely contested."
+    },
+    "exec-summary": {
+      "tier": "standard",
+      "rationale": "Compression to one page. Needs to keep the right signal; escalate on very long source docs."
+    },
+    "figma-diagrams": {
+      "tier": "standard",
+      "rationale": "API calls + spec generation. Bounded transformation."
+    },
+    "guide-builder": {
+      "tier": "standard",
+      "rationale": "Shapes notes into a styled guide. Generation, not adversarial review."
+    },
+    "reverse-architecture": {
+      "tier": "standard",
+      "rationale": "Extracts architecture from code/IaC. Escalate to heavy on large codebases where cross-file inference is heavy."
+    },
+    "runbook-generator": {
+      "tier": "standard",
+      "rationale": "Operational doc from service facts. Bounded synthesis."
+    },
+    "slide-outliner": {
+      "tier": "standard",
+      "rationale": "Outlines a deck to a time budget. Structuring, not deep reasoning."
+    },
+    "sonar-review": {
+      "tier": "standard",
+      "rationale": "Formats Sonar API findings into a report. The hard analysis is Sonar's; this is synthesis. Escalate on very large diffs."
+    },
+    "ai-usage-report": {
+      "tier": "standard",
+      "rationale": "Tabulates telemetry into a report. Mostly mechanical, but the 'AI theater' effectiveness call needs judgment."
+    },
+    "ai-readiness-assessment": {
+      "tier": "standard",
+      "rationale": "Scores six fixed dimensions against a rubric and ranks gaps by blocking order. Bounded structured judgment, not adversarial reasoning; escalate via ambiguous-input when the evidence is thin or contested."
+    },
+    "agent-adoption-stage": {
+      "tier": "standard",
+      "rationale": "Places a team on a fixed 5-stage ladder from observables and routes one unlock. Bounded diagnosis against a rubric; escalate via ambiguous-input when the observables are contradictory or the distribution is heavily skewed."
+    },
+    "ai-use-case-triage": {
+      "tier": "standard",
+      "rationale": "Scores candidates on weighted axes and forces a rejection list. Structured comparison with stated weights; escalate via ambiguous-input when candidates are numerous or the value data is contested."
+    },
+    "ai-adoption-rollout": {
+      "tier": "standard",
+      "rationale": "Generates a phased people-rollout with gates and enablement from a stated tool and population. Structured planning against a fixed shape; escalate via ambiguous-input for large or politically contested rollouts."
+    },
+    "ai-usage-policy": {
+      "tier": "standard",
+      "rationale": "Drafts a policy document against a fixed structure (tiers, behaviours, review matrix, exception route). Bounded generation; escalate via ambiguous-input where a regulatory regime is named or contested."
+    },
+    "feature-implement-loop": {
+      "tier": "standard",
+      "rationale": "Code + test generation against acceptance criteria. The adversarial pass delegates to devils-advocate (heavy) where available; the loop itself is generation."
+    },
+    "pre-merge-review": {
+      "tier": "standard",
+      "rationale": "Orchestration: runs a deterministic gate script, dispatches the (heavy) reviewer subagents, and renders a rule-based go/no-go. The adversarial reasoning is delegated to the panel, so the skill itself is coordination."
+    },
+    "user-story-splitter": {
+      "tier": "standard",
+      "rationale": "Decomposes an epic into INVEST slices with testable ACs. Structured synthesis; escalation rules cover large or contradictory PRDs."
+    },
+    "test-plan-generator": {
+      "tier": "standard",
+      "rationale": "Synthesizes a structured plan from a change description. Risk ranking needs judgment but is bounded; escalate via ambiguous-input on contested or high-stakes releases."
+    },
+    "release-notes": {
+      "tier": "standard",
+      "rationale": "Classifies commits and rewrites them for a reader. The audience translation needs judgment; escalate via large-input on very long ranges."
+    },
+    "postmortem-generator": {
+      "tier": "standard",
+      "rationale": "Synthesizes a structured doc from incident notes. Contributing-factor chains need judgment but are bounded; escalate via large-input on huge scrollbacks."
+    },
+    "migration-plan": {
+      "tier": "standard",
+      "rationale": "Phased plan synthesis with a strong template. Ordering judgment is bounded by the expand/migrate/contract pattern; escalate via ambiguous-input on contested, high-stakes cutovers."
+    },
+    "api-contract-draft": {
+      "tier": "standard",
+      "rationale": "Schema synthesis against fixed conventions. The resource modeling needs judgment; the conventions bound it. Escalate via ambiguous-input on contested multi-team contracts."
+    },
+    "bug-triage": {
+      "tier": "standard",
+      "rationale": "Extraction plus judgment calls (severity vs priority, hypothesis ranking) \u2014 same shape as brief-intake: above light, below heavy."
+    },
+    "prd-draft": {
+      "tier": "standard",
+      "rationale": "Synthesizes a structured requirements doc from a brief. The solution-language discipline needs care; bounded by the template. Escalate via ambiguous-input on contested scope."
+    },
+    "nfr-spec": {
+      "tier": "standard",
+      "rationale": "Rubric-driven sweep with archetype defaults; the judgment is calibrating targets to business reality. Bounded by the catalog; escalate via ambiguous-input on contested SLOs."
+    },
+    "success-metrics": {
+      "tier": "standard",
+      "rationale": "Structured measurement design; the primary-metric and counter-metric choices need judgment but the template bounds it. Escalate via ambiguous-input when the goal itself is contested."
+    },
+    "requirements-interview": {
+      "tier": "standard",
+      "rationale": "Question banks are rubric-shaped, but ranking by design impact and deriving falsification conditions for the specific feature is synthesis \u2014 above light."
+    },
+    "business-case": {
+      "tier": "heavy",
+      "rationale": "Weighted multi-option judgment with a committal recommendation \u2014 same failure mode as tech-comparison-matrix: cheaper models mis-weight costs, inflate benefits, and miss the flip-assumption. Never downgrade."
+    },
+    "incident-comms": {
+      "tier": "standard",
+      "rationale": "Audience-segmented message generation under a strict don't-retract discipline. Same shape as exec-summary/audience-profile \u2014 translation and altitude, not adversarial reasoning."
+    },
+    "data-contract": {
+      "tier": "standard",
+      "rationale": "Schema + SLA synthesis against fixed quality dimensions and an evolution matrix. Semantics capture needs care; bounded by the catalog. Escalate via large-input on wide schemas."
+    },
+    "llm-eval-harness": {
+      "tier": "standard",
+      "rationale": "Methodology synthesis against a fixed decision tree and pitfall catalog. Grading-method and metric choices need judgment but are bounded; escalate via ambiguous-input on novel task types."
+    },
+    "capacity-cost-model": {
+      "tier": "standard",
+      "rationale": "Quantitative projection from a demand model against a fixed cost catalog. Headroom and scaling-cliff judgment is bounded by the reference; escalate via ambiguous-input on novel architectures."
+    },
+    "accessibility-audit": {
+      "tier": "heavy",
+      "rationale": "Adversarial review against WCAG success criteria \u2014 cheaper models fault alt-text presence over quality, under-call severity, miss focus-order/name-role-value issues, and claim AT passes from screenshots. Never downgrade."
+    },
+    "db-schema-design": {
+      "tier": "standard",
+      "rationale": "Design synthesis from access patterns against a fixed paradigm/indexing/anti-pattern reference. Paradigm and denormalization judgment is bounded; escalate via ambiguous-input on contested scale/consistency tradeoffs."
+    },
+    "observability-plan": {
+      "tier": "standard",
+      "rationale": "Methodology synthesis against fixed SRE practices (golden signals, burn-rate alerting, pillar split). SLO calibration needs judgment but is bounded; escalate via ambiguous-input on contested reliability targets."
+    },
+    "council-review": {
+      "tier": "heavy",
+      "rationale": "Multi-perspective deliberation + weighted reconciliation across distinct expert seats. Cheaper models collapse the seats into one voice and either manufacture or miss the real cruxes. Never downgrade."
+    },
+    "devils-advocate": {
+      "tier": "heavy",
+      "rationale": "Adversarial code review across four lenses. Cheaper models miss edge cases and under-call severity \u2014 the whole value is the hard thinking. Never downgrade."
+    },
+    "output-hygiene": {
+      "tier": "standard",
+      "rationale": "The mechanical pass is a deterministic script; the model does bounded rewriting of flagged prose against a fixed tell list, not adversarial review."
+    },
+    "doc-critique": {
+      "tier": "heavy",
+      "rationale": "Adversarial doc review against rubrics. Same as devils-advocate: the value is catching what a fast pass misses. Never downgrade."
+    },
+    "tech-comparison-matrix": {
+      "tier": "heavy",
+      "rationale": "Weighted multi-criteria judgment with a recommendation. Mis-weighting is the failure mode; heavy is worth it. Never downgrade."
+    },
+    "threat-model": {
+      "tier": "heavy",
+      "rationale": "Adversarial reasoning over a design \u2014 cheaper models emit checklist residue, miss authz/insider paths, and inflate severity. Never downgrade."
+    },
+    "prfaq": {
+      "tier": "standard",
+      "rationale": "Synthesizes a press release and FAQs from a product concept against a fixed format. The specificity discipline needs care but the template bounds it; escalate via ambiguous-input when the concept itself is contested."
+    },
+    "okr-cascade": {
+      "tier": "standard",
+      "rationale": "Structured derivation against a fixed roll-up discipline; the causal-sentence and gap judgments need care but the template bounds them. Escalate via ambiguous-input when the company objectives themselves are contested."
+    },
+    "user-journey-map": {
+      "tier": "standard",
+      "rationale": "Structured synthesis into a fixed four-row stage model plus bounded ranking judgment. Escalate via ambiguous-input when the persona or outcome is contested or research inputs conflict."
+    },
+    "strategy-analysis": {
+      "tier": "heavy",
+      "rationale": "Framework selection plus evidenced multi-factor judgment ending in a ranked, committal verdict. Cheaper models fill cells with generic filler, skip the TOWS crossings, and refuse to take a side. Never downgrade."
+    },
+    "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 \u2014 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 \u2014 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."
+    },
+    "prompt-caching-advisor": {
+      "tier": "standard",
+      "rationale": "Structural analysis of prompt with threshold arithmetic and pattern matching \u2014 above light, no need for heavy."
+    },
+    "token-budget-estimator": {
+      "tier": "standard",
+      "rationale": "Arithmetic breakdown plus heuristic judgment on dominant cost drivers \u2014 standard fits."
+    },
+    "eval-harness-generator": {
+      "tier": "standard",
+      "rationale": "Reads a SKILL.md and synthesizes eval cases \u2014 requires understanding of skill intent but not heavy reasoning."
+    },
+    "tool-use-schema-writer": {
+      "tier": "standard",
+      "rationale": "Schema generation from natural-language description \u2014 structured output task that fits standard tier."
+    },
+    "contribution-wizard": {
+      "tier": "standard",
+      "rationale": "Intake plus structured generation \u2014 standard tier covers template-filling and schema-adherence judgment."
+    }
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "Portable AI-agent skills for the deliverables knowledge workers ship \u2014 diagrams, ADRs, PRDs, runbooks, decks, reviews \u2014 installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs.json

@@ -61,7 +61,8 @@
         "sonar-onboard",
         "sonar-review",
         "accessibility-audit",
-        "output-hygiene"
+        "output-hygiene",
+        "contribution-wizard"
       ]
     },
     "sre-oncall": {
@@ -107,6 +108,16 @@
         "ai-usage-policy",
         "agent-adoption-stage"
       ]
+    },
+    "claude-api": {
+      "description": "Skills for teams building on the Anthropic API — prompt caching, token budgeting, eval generation for skills, and tool-use schema writing.",
+      "loops": [],
+      "skills": [
+        "prompt-caching-advisor",
+        "token-budget-estimator",
+        "eval-harness-generator",
+        "tool-use-schema-writer"
+      ]
     }
   },
   "outcomes": {
@@ -159,7 +170,18 @@
         "test-plan-generator",
         "bug-triage",
         "agents-md-generator",
-        "llm-eval-harness"
+        "llm-eval-harness",
+        "eval-harness-generator",
+        "contribution-wizard"
+      ]
+    },
+    "build-on-the-claude-api": {
+      "description": "Skills for teams building directly on the Anthropic API — prompt caching strategy, token budgeting, eval generation, and tool-use schema writing.",
+      "skills": [
+        "prompt-caching-advisor",
+        "token-budget-estimator",
+        "eval-harness-generator",
+        "tool-use-schema-writer"
       ]
     },
     "run-and-recover-the-service": {

package/skills/contribution-wizard/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: contribution-wizard
+description: Guides an author through creating a new skilldrop skill from scratch — generates the manifest, SKILL.md, eval cases, and README entry from a plain-language description of the skill's purpose. Use when authoring a new skill for this repo or a private fork, ensuring a new skill meets the schema and validation requirements before submission.
+---
+
+# contribution-wizard
+
+Walks an author through the full arc of creating a new skilldrop skill: intake → manifest + SKILL.md + evals + README entry. The output is copy-paste-ready — the author drops the files into `skills/<name>/` and runs `python3 validate.py` to confirm before opening a PR.
+
+## How to respond
+
+### Step 1 — Intake (ask all at once)
+
+Ask these questions in a single block — not one at a time:
+
+> **New skill intake**
+>
+> 1. **Purpose**: what does this skill do in one sentence?
+> 2. **Input**: what does the agent receive? (paste, file, structured data, conversational context)
+> 3. **Output**: what does the agent produce? (artifact type, format, length)
+> 4. **Pack**: which role pack does it belong to? (solution-architect / product-manager / dev-team / sre-oncall / stakeholder-comms / ai-engineering / claude-api / new pack)
+> 5. **Is it a gate?** Does it emit a pass/fail verdict, or generate an artifact?
+> 6. **Related skills**: which existing skills does it complement or hand off to?
+> 7. **External deps**: does it need API keys, npm packages, or pip libraries?
+
+### Step 2 — Generate all artifacts in one response
+
+After intake, produce the following in a single response, each in its own fenced code block:
+
+#### `manifest.json`
+
+```json
+{
+  "name": "<kebab-case-name>",
+  "version": "1.0.0",
+  "description": "<use-case-first description — what it does, then trigger phrases>",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["<related-skill-1>", "<related-skill-2>"],
+  "tags": ["<tag1>", "<tag2>"],
+  "model": {
+    "tier": "<light|standard|heavy>",
+    "rationale": "<one sentence: why this tier fits what the skill does>"
+  }
+}
+```
+
+Tier guidance:
+- **light**: pattern matching, formatting, extraction with no judgment calls
+- **standard**: synthesis, judgment calls, structured output requiring reasoning (most skills)
+- **heavy**: multi-step reasoning with high stakes or adversarial review (gates, threat models)
+
+#### `SKILL.md`
+
+```markdown
+---
+name: <skill-name>
+description: <same as manifest description>
+---
+
+# <skill-name>
+
+<One paragraph: what this skill does and why it's useful. Name the problem it solves.>
+
+## How to respond
+
+<Numbered steps. Each step is an observable action. No vague "reason about X" steps.>
+
+## Quality bar
+
+<Three to five bullet points: what a good output includes and what it never does. Name anti-patterns explicitly.>
+```
+
+#### `evals/cases.json`
+
+Eight eval cases covering: 2 happy-path, 2 minimal/edge input, 2 anti-pattern (the quality bar failures), 2 refusal or boundary cases. Format:
+
+```json
+[
+  {
+    "id": "happy-path-standard",
+    "trigger": "<realistic input>",
+    "expected_shape": ["<checkable criterion 1>", "<checkable criterion 2>"],
+    "must_not_include": ["<anti-pattern from quality bar>"],
+    "verdict_class": "pass",
+    "notes": "<one sentence on what this tests>"
+  }
+]
+```
+
+#### `README.md` entry
+
+One row for the skill table, matching the format of existing rows:
+
+```
+| [`<skill-name>`](skills/<skill-name>/SKILL.md) | <One sentence describing what the skill does and the output it produces.> |
+```
+
+#### `packs.json` addition
+
+State which pack to add the skill to and the exact line to add to the skills array.
+
+### Step 3 — Install check reminder
+
+After generating, tell the author:
+
+```
+Next steps:
+1. mkdir skills/<skill-name> && cd skills/<skill-name>
+2. Drop in manifest.json, SKILL.md, and evals/cases.json
+3. python3 validate.py    # must pass before opening a PR
+4. Add the README row to the correct section
+5. Add the skill to packs.json under the right pack
+6. If the skill has a how-to guide, add it to guides/how-to/ and guides/README.md
+```
+
+## Anti-patterns
+
+- **Generating manifests without checking the schema.** The most common contribution failure is a manifest missing a required field. Always instruct the author to run `python3 validate.py` before opening a PR.
+- **Generating eval triggers that test nothing.** "Run this skill" is not an eval case. Insist on realistic triggers that would expose a specific failure mode if the model got it wrong.
+- **Listing related skills that don't exist.** A manifest that references a non-existent skill fails validation. Instruct the author to run `ls skills/` before finalizing the `related` array.
+
+After generating eval cases, the author can use `eval-harness-generator` to add more coverage or to regenerate cases after modifying the SKILL.md.
+
+## Quality bar
+
+- **Manifests must be schema-valid.** Every field required by `contracts/skill.schema.json` must be present. Use `python3 validate.py` as the check — not a visual review.
+- **Eval triggers are realistic.** A trigger of "use this skill" is not an eval case. Each trigger should be a plausible user input, not a test harness artifact.
+- **SKILL.md has observable steps.** Every step in "How to respond" must describe an action the agent takes — never "think about X" or "consider Y".
+- **The quality bar names anti-patterns.** A quality bar that only says what good looks like doesn't help the agent avoid common failures. Name at least two things the output must never do.
+- **Related skills are real.** Every skill listed in `related` must exist in the skills directory. Run `ls skills/` to check before outputting.

package/skills/contribution-wizard/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "contribution-wizard",
+  "version": "1.0.0",
+  "description": "Guides an author through creating a new skilldrop skill from scratch — generates the manifest, SKILL.md, eval cases, and README entry from a plain-language description of the skill's purpose. Use when authoring a new skill for this repo or a private fork, ensuring a new skill meets the schema and validation requirements before submission.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["eval-harness-generator"],
+  "tags": ["meta", "authoring", "contribution", "skilldrop-meta"],
+  "model": { "tier": "standard", "rationale": "Intake + structured generation — standard tier covers the template-filling and schema-adherence judgment this requires." }
+}

package/skills/eval-harness-generator/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: eval-harness-generator
+description: Takes a skill's SKILL.md and generates a set of eval cases — trigger queries, expected output shape, and pass/fail criteria — ready to drop into the skill's evals/ directory. Use when adding evals to a new or existing skill, verifying a skill behaves as documented, or building a regression gate before modifying a skill.
+---
+
+# eval-harness-generator
+
+Reads a SKILL.md and generates eval cases that cover the skill's happy path, edge cases, and known failure modes. The output is JSON that drops directly into `skills/<name>/evals/cases.json`. Unlike `llm-eval-harness` (which designs eval harnesses for arbitrary LLM features), this skill specifically targets the skilldrop eval format and the patterns that skilldrop skills routinely get wrong.
+
+## How to respond
+
+### Step 1 — Read the skill
+
+Ask the user to paste the full SKILL.md. Extract:
+- What the skill takes as input
+- What the skill produces as output
+- Any explicit quality bars or anti-patterns the skill names
+- Whether the skill is a **gate** (emits a verdict from `contracts/terminals.json`) or a **generator** (produces an artifact)
+
+### Step 2 — Identify failure modes
+
+Before writing cases, enumerate the failure modes the eval set should catch:
+
+| Category | Failure mode to test |
+|---|---|
+| **Happy path** | Standard input produces the expected artifact/verdict |
+| **Minimal input** | Sparse or ambiguous input — does the skill ask clarifying questions rather than hallucinate? |
+| **Anti-pattern input** | Input that would tempt the skill to produce a common bad output (named in the SKILL.md's quality bar) |
+| **Edge input** | Boundary conditions specific to this skill (e.g., a bug report with no repro steps for bug-triage) |
+| **Gate refusal** | For gate skills: input that should produce BLOCKED or REVISE, not PROCEED |
+
+### Step 3 — Generate the eval cases
+
+Produce a JSON array with 8–12 cases. Each case:
+
+```json
+{
+  "id": "happy-path-standard",
+  "trigger": "The exact query or input that activates this case",
+  "expected_shape": [
+    "Output contains a <specific element>",
+    "Output names a specific field or section",
+    "Output avoids <anti-pattern named in quality bar>"
+  ],
+  "must_not_include": [
+    "Fabricated detail not present in the input",
+    "A verdict word from the wrong class (for gate skills)"
+  ],
+  "verdict_class": "pass",
+  "notes": "One sentence on what this case is testing and why it matters"
+}
+```
+
+For gate skills, use `verdict_class` values from `contracts/terminals.json`: `pass`, `conditional`, `revise`, `redirect`, `blocked`. For generators, use `pass` / `fail`.
+
+### Step 4 — Write an eval strategy note
+
+After the JSON array, add a brief eval strategy note (3–5 sentences) explaining:
+- Which cases cover which failure modes
+- The most important case and why
+- What a regression on which case would mean
+
+### Step 5 — Remind about placement
+
+Tell the user:
+```
+Drop this into skills/<skill-name>/evals/cases.json
+Run: python3 validate.py   # confirms the file is found
+```
+
+## Anti-patterns
+
+- **Triggers that don't test anything.** "Run the skill on this input" is not a meaningful trigger. Each trigger must be specific enough that a failing model would produce a wrong output you'd recognize.
+- **expected_shape items that can't be checked.** "Output is comprehensive" is not checkable. Name specific sections, fields, or behaviors.
+- **Missing anti-pattern cases.** The most common eval gap is no cases that test the quality bar's failure modes. If a skill says "never present a hypothesis as the cause," there must be a case where the input tempts that failure.
+
+For designing eval harnesses for general LLM features (not skilldrop skills specifically), use `llm-eval-harness` instead. Use `contribution-wizard` when creating a new skill from scratch — it calls this skill as part of the authoring flow.
+
+## Quality bar
+
+- **Triggers must be realistic.** A trigger of "run this skill" is not an eval case — it doesn't test anything specific. Each trigger should be the kind of input a real user would paste.
+- **expected_shape items must be checkable.** "Output is good" is not checkable. "Output contains a numbered repro sequence starting from a clean state" is.
+- **Cover the refusal cases.** The most common gap in skilldrop evals is missing cases for the skill's anti-patterns — the bad outputs the quality bar explicitly forbids. At least 2 of the 8–12 cases must test that the skill refuses or avoids its stated failure mode.
+- **Don't pad to 12.** Eight strong cases beat twelve weak ones. Only add cases that test a distinct failure mode not already covered.

package/skills/eval-harness-generator/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "eval-harness-generator",
+  "version": "1.0.0",
+  "description": "Takes a skill's SKILL.md and generates a set of eval cases — trigger queries, expected output shape, and pass/fail criteria — ready to drop into the skill's evals/ directory. Use when adding evals to a new or existing skill, verifying a skill behaves as documented, or building a regression gate before modifying a skill.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["llm-eval-harness", "contribution-wizard"],
+  "tags": ["claude-api", "evals", "testing", "quality", "skilldrop-meta"],
+  "model": { "tier": "standard", "rationale": "Reads a SKILL.md and synthesizes eval cases — requires understanding of the skill's intent but not heavy reasoning." }
+}

package/skills/prompt-caching-advisor/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: prompt-caching-advisor
+description: Analyzes a prompt or conversation structure and identifies the highest-value cache breakpoints — where to insert cache_control checkpoints to minimize repeated token processing. Use when designing or optimizing a Claude API integration that uses prompt caching, when input costs are dominated by a static system prompt or few-shot block, or when a multi-turn conversation reprocesses the same context on every turn.
+---
+
+# prompt-caching-advisor
+
+Identifies where to place `cache_control` checkpoints in a Claude API prompt or conversation structure to minimize repeated token processing. The savings are real — a cache hit on a 10,000-token system prompt costs ~90% less than re-processing it — but the placement matters. Wrong breakpoints waste the minimum cacheable block size or cache dynamic content that never hits.
+
+## How to respond
+
+### Step 1 — Understand the structure
+
+Ask the user to share (or describe) their prompt structure. You need:
+- The system prompt (or a description of what's in it and roughly how long)
+- Any few-shot examples passed in messages
+- The shape of the variable user turn (what changes per request)
+- Whether this is single-turn or multi-turn
+
+If they share code, read the messages array. The cache breakpoint goes at the end of the block you want cached — a `cache_control: {"type": "ephemeral"}` on the **last content block** of a message causes everything up to and including that block to be cached.
+
+### Step 2 — Classify each block
+
+For each distinct block, classify it:
+
+| Class | Characteristics | Cache? |
+|---|---|---|
+| **Static** | Same on every request (system instructions, reference docs, few-shot examples) | Yes — put breakpoint at the end |
+| **Quasi-static** | Same for a session or user, different across users (user profile, project context) | Yes, with session-scope awareness |
+| **Dynamic** | Changes every request (current user message, real-time data, timestamps) | No — never cache |
+
+### Step 3 — Recommend breakpoints
+
+State exactly where to place each `cache_control` checkpoint. Show the code:
+
+```python
+messages = [
+    {
+        "role": "user",
+        "content": [
+            {
+                "type": "text",
+                "text": "<static few-shot examples here>",
+                "cache_control": {"type": "ephemeral"}  # breakpoint 1 — caches system + examples
+            },
+            {
+                "type": "text",
+                "text": user_query  # dynamic — no cache_control
+            }
+        ]
+    }
+]
+```
+
+For system prompts, the cache breakpoint goes on the last block of the system array.
+
+### Step 4 — Estimate cache hit rate
+
+Give a rough hit rate estimate:
+- **Near 100%**: static system prompt, fixed few-shot examples, no dynamic injection into the cached block
+- **~session %**: user-context cached per-session; hits on turn 2+, misses on first turn per user
+- **Low**: anything that embeds timestamps, UUIDs, or per-request data in the cached block
+
+### Step 5 — Warn on sub-threshold blocks
+
+Warn if a block the user wants to cache is likely under the minimum cacheable size:
+- **Haiku**: ~1,024 tokens minimum
+- **Sonnet / Opus**: ~2,048 tokens minimum
+
+A block under the minimum is processed as normal — no error, just no cache savings. Calculate roughly: 1 token ≈ 4 characters of English prose. A 2,000-character system prompt (~500 tokens) won't benefit on Sonnet/Opus.
+
+### Step 6 — Output format
+
+Produce:
+1. **Annotated structure** — show the messages array with `cache_control` placements marked and commented
+2. **Cache strategy summary** — one paragraph: what is cached, why, expected hit rate, and the dominant cost driver before and after
+
+## Anti-patterns
+
+- **Caching dynamic content.** If a user query, timestamp, or per-request database result is inside a cached block, every request is a cache miss — the structure defeats itself. Identify and flag before recommending.
+- **Recommending a cache on a block under the minimum size.** A 300-token block doesn't cache on Sonnet/Opus. The API doesn't error — it just processes normally. Always check size before recommending.
+- **Recommending four or more breakpoints.** More than three breakpoints on a single request is almost always a sign the prompt structure should be simplified, not patched with caches.
+
+Use `token-budget-estimator` after this skill if the user also wants to size the token budget across components.
+
+## Quality bar
+
+- **Never cache dynamic content.** A user query, a timestamp, a database result retrieved per-request — these must not appear in a cached block. If the user's structure embeds dynamic content in an otherwise static block, flag it before recommending the cache.
+- **One breakpoint per logical boundary.** A system prompt with three sections (instructions, reference docs, examples) can have up to three breakpoints. More than four breakpoints on a single request is a signal the structure needs rethinking.
+- **The last block caches everything before it.** This is the most common misunderstanding — the cache breakpoint is not a marker for just that block, it's a marker for the entire prefix up to that point.

package/skills/prompt-caching-advisor/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "prompt-caching-advisor",
+  "version": "1.0.0",
+  "description": "Analyzes a prompt or conversation structure and identifies the highest-value cache breakpoints — where to insert cache_control checkpoints to minimize repeated token processing. Use when designing or optimizing a Claude API integration that uses prompt caching, when input costs are dominated by a static system prompt or few-shot block, or when a multi-turn conversation reprocesses the same context on every turn.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["token-budget-estimator"],
+  "tags": ["claude-api", "caching", "cost", "optimization", "prompt-engineering"],
+  "model": { "tier": "standard", "rationale": "Structural analysis of a prompt with threshold arithmetic and pattern matching — above light (needs API-specific judgment), no need for heavy." }
+}

package/skills/token-budget-estimator/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: token-budget-estimator
+description: Estimates input and output token usage for a described agentic workflow, surfaces the dominant cost drivers, and suggests max_tokens budget controls per component. Use when planning a new Claude API integration, sizing a cost budget for a feature, or diagnosing why a workflow's token usage is higher than expected.
+---
+
+# token-budget-estimator
+
+Breaks down token usage for an agentic workflow — before you build it or while diagnosing runaway costs. The output is a component table (not a single number) because "how many tokens does this use?" has a different answer for the system prompt, the growing context window, tool results, and the final output. Knowing which component dominates tells you where to optimize.
+
+## How to respond
+
+### Step 1 — Intake
+
+Ask the user to describe their workflow. Collect:
+- What the agent does (brief description)
+- The shape of the system prompt (static instructions, injected context, few-shot examples — rough character/word count is fine)
+- How many turns or tool calls a typical session has
+- What tool results look like (small JSON blobs? Full document retrieval? Database rows?)
+- Roughly how long the final output is
+
+If they already have working code or logs, ask them to share a sample API request/response — you can count tokens more accurately from the actual content.
+
+### Step 2 — Estimate each component
+
+Build a token budget table. Token approximation: **1 token ≈ 4 characters** of English text; code/JSON runs denser (~3 chars/token).
+
+| Component | Est. tokens | Notes |
+|---|---|---|
+| System prompt | X | Static — same every call |
+| Injected context (per call) | X | User data, retrieved docs, etc. |
+| Few-shot examples | X | Static — cache candidate |
+| User turn (per call) | X | Variable per request |
+| Tool definitions | X | Sent on every call that uses tools |
+| Tool results (per turn) | X | Accumulate across turns |
+| Context accumulation | X | Previous turns retained in window |
+| Output (per call) | X | Depends on max_tokens and task |
+| **Total per session** | X | Sum across all turns |
+
+Flag the **dominant cost driver** — the single row with the largest token count — and explain why it dominates.
+
+### Step 3 — Recommend budget controls
+
+For each component, suggest a concrete control:
+
+- **System prompt too large**: split static vs dynamic; cache the static portion (`prompt-caching-advisor`)
+- **Context accumulation**: summarize earlier turns, or use a sliding window instead of full history
+- **Tool results**: truncate or paginate large results before passing to the model; never inject a 50-row database result when 5 representative rows suffice
+- **Output**: set `max_tokens` to the realistic output ceiling — open-ended `max_tokens` on a generation task wastes budget on over-generation
+- **Tool definitions**: only send the tools relevant to the current task state (tool selection narrows with progress)
+
+### Step 4 — Extended thinking note
+
+If the workflow uses extended thinking (`betas: ["interleaved-thinking"]`), add a note: thinking tokens are billed at the same input rate and are subject to a `budget_tokens` cap you set. Recommend setting `budget_tokens` to 2–4× the typical output length for reasoning tasks, and lower for classification or extraction tasks where long thinking chains rarely help.
+
+### Step 5 — Output format
+
+Produce:
+1. **Token budget table** — the component breakdown with estimates
+2. **Dominant driver** — named and explained
+3. **Three concrete controls** — ranked by expected savings, with specific API parameters where applicable (`max_tokens`, `cache_control`, tool selection logic)
+4. **Rough cost estimate** — using current public pricing for the tier the user is on (state the tier assumption; don't guess if unknown)
+
+## Anti-patterns
+
+- **A single total without a breakdown.** "~50,000 tokens per session" tells a developer nothing actionable. Always produce the component table.
+- **False precision from descriptions.** "3,142 tokens" from a description is theatre. Use ranges; tighten only when working from actual content.
+- **Optimizations without a ranking.** Listing five suggestions without saying which saves the most wastes the developer's attention.
+
+For caching-specific advice after sizing the budget, hand off to `prompt-caching-advisor`. For agent-level spending controls, see `agent-budget`.
+
+## Quality bar
+
+- **Ranges over false precision.** "~2,000–4,000 tokens" is more honest than "3,142 tokens" when you're working from a description. Use ranges when working from descriptions, tighter estimates when working from actual content.
+- **The table beats the total.** A single "~50,000 tokens per session" is nearly useless — the table that shows context accumulation accounts for 40,000 of those gives the developer somewhere to act.
+- **Name the optimization target.** Don't list five optimizations without ranking them. The one that saves 80% of the dominant component beats the one that shaves 5% off a small component.

package/skills/token-budget-estimator/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "token-budget-estimator",
+  "version": "1.0.0",
+  "description": "Estimates input and output token usage for a described agentic workflow, surfaces the dominant cost drivers, and suggests max_tokens budget controls per component. Use when planning a new Claude API integration, sizing a cost budget for a feature, or diagnosing why a workflow's token usage is higher than expected.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["prompt-caching-advisor", "agent-budget"],
+  "tags": ["claude-api", "cost", "tokens", "planning", "budgeting"],
+  "model": { "tier": "standard", "rationale": "Arithmetic breakdown plus heuristic judgment on dominant cost drivers — standard fits; no heavy reasoning needed." }
+}

package/skills/tool-use-schema-writer/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: tool-use-schema-writer
+description: Takes a function description (name, purpose, parameters) and writes a valid Anthropic tool_use JSON schema, with type annotations, required fields, and a description for each parameter. Produces a Python usage snippet for client.messages.create(tools=[...]). Use when wiring a Claude agent to a function or API, designing tools for a multi-agent system, or documenting an existing tool for agent consumption.
+---
+
+# tool-use-schema-writer
+
+Converts a natural-language function description into a valid Anthropic `tool_use` definition. The output is ready to paste into `client.messages.create(tools=[...])`. This skill enforces the two constraints that cause most tool-use bugs: descriptions that are too vague for the model to choose the right tool, and missing `required` arrays that cause the model to omit non-optional fields.
+
+## How to respond
+
+### Step 1 — Intake
+
+Ask the user to describe the function. Collect:
+- **Name** (snake_case preferred; the model uses this to call the tool)
+- **Purpose** (one sentence: what does this function do and when should the model call it?)
+- **Parameters**: for each — name, type, what it means, whether it's required
+- **Return value** (optional — for documentation purposes only; the model doesn't see it)
+
+If they share existing code (Python, TypeScript, etc.), read the function signature and docstring directly.
+
+### Step 2 — Write the tool definition
+
+Produce a valid Anthropic tool definition:
+
+```json
+{
+  "name": "function_name",
+  "description": "One to three sentences. State what the function does, when the model should call it (the decision condition), and what it returns. Avoid vague descriptions like 'performs an operation' — the model reads this to decide whether to call the tool.",
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "param_name": {
+        "type": "string",
+        "description": "What this parameter controls and what values are valid. Include the unit if numeric (e.g., 'timeout in seconds, 1–300')."
+      },
+      "another_param": {
+        "type": "integer",
+        "description": "..."
+      },
+      "enum_param": {
+        "type": "string",
+        "enum": ["value_a", "value_b"],
+        "description": "Which mode to use. value_a does X; value_b does Y."
+      }
+    },
+    "required": ["param_name"]
+  }
+}
+```
+
+Valid JSON Schema types for Anthropic tool parameters: `"string"`, `"integer"`, `"number"`, `"boolean"`, `"array"`, `"object"`, `"null"`. Arrays need `"items"`. Objects need `"properties"` and their own `"required"`.
+
+### Step 3 — Validate
+
+Check the definition against these rules before outputting:
+- Every parameter in `"required"` exists in `"properties"`
+- No parameter has an empty `"description"` — the model needs these to fill values correctly
+- The top-level `"description"` names a decision condition ("call this when X"), not just what it does
+- Enum values are listed in the parameter description with a one-phrase explanation each
+- Nested objects have their own `"required"` arrays
+
+### Step 4 — Python usage snippet
+
+Produce the Python snippet:
+
+```python
+import anthropic
+
+client = anthropic.Anthropic()
+
+tools = [
+    {
+        "name": "function_name",
+        "description": "...",
+        "input_schema": { ... }
+    }
+]
+
+response = client.messages.create(
+    model="claude-sonnet-5-5",
+    max_tokens=1024,
+    tools=tools,
+    messages=[{"role": "user", "content": "Your prompt here"}]
+)
+
+# Handle tool use
+if response.stop_reason == "tool_use":
+    tool_use_block = next(b for b in response.content if b.type == "tool_use")
+    tool_input = tool_use_block.input  # dict matching your schema
+    result = function_name(**tool_input)
+    # Send result back in a follow-up message
+```
+
+### Step 5 — Multi-tool note
+
+If the user describes multiple functions, produce one JSON array with all tools and remind them: the model chooses among all tools on each turn, so descriptions must be distinct enough to make the right call unambiguous. If two tools do similar things, the description must name the exact condition that separates them.
+
+## Anti-patterns
+
+- **Descriptions that restate the function name.** `"Gets the weather"` for a function named `get_weather` tells the model nothing about when to call it. Descriptions must name the decision condition.
+- **Omitting the `required` array.** Without `required`, all fields are optional — the model will skip non-optional parameters, causing runtime errors.
+- **Enum values without descriptions.** `"enum": ["asc", "desc"]` without explanation leaves the model guessing; it will sometimes pick the wrong value.
+
+For the agent loop that calls these tools, see `agent-loop-design`. For orchestrating multiple agents that each expose tool schemas, see `subagent-design`.
+
+## Quality bar
+
+- **Descriptions are decision conditions, not function names restated.** `"Gets the weather"` is not a description — `"Returns the current temperature and conditions for a given city. Call this when the user asks about current weather, not forecasts."` is.
+- **Required arrays are never omitted.** An omitted `required` array means all fields are optional — the model will skip fields the function actually needs and the call will fail at runtime.
+- **Enum values always have descriptions.** `"enum": ["asc", "desc"]` without a description leaves the model guessing which to use.

package/skills/tool-use-schema-writer/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "tool-use-schema-writer",
+  "version": "1.0.0",
+  "description": "Takes a function description (name, purpose, parameters) and writes a valid Anthropic tool_use JSON schema, with type annotations, required fields, and a description for each parameter. Produces a Python usage snippet for client.messages.create(tools=[...]). Use when wiring a Claude agent to a function or API, designing tools for a multi-agent system, or documenting an existing tool for agent consumption.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["agent-loop-design", "subagent-design"],
+  "tags": ["claude-api", "tool-use", "json-schema", "sdk", "agents"],
+  "model": { "tier": "standard", "rationale": "Schema generation from a natural-language description — structured output task that fits standard tier." }
+}