skilldrop-cli 0.12.2 → 0.13.1

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 63 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:
+**63 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.
@@ -24,13 +24,14 @@ skilldrop ships **loops**, not just parts. A loop is a named sequence of stages
 
 A loop *sequences* skills — it never contains one. Every skill stays independently installable and runnable on its own, which is what keeps a single-folder copy working in Cursor, Kiro, or Aider.
 
-Four loops cover the lifecycle, and they are separated by **reversibility** — how expensive the mistake is to unwind — which is why each gets its own gate rather than folding into a neighbour:
+Five loops cover the lifecycle, and they are separated by **reversibility** — how expensive the mistake is to unwind — which is why each gets its own gate rather than folding into a neighbour:
 
 | Loop | Takes | Gate | Produces | Mistake costs |
 |---|---|---|---|---|
 | [`discover`](loops/discover/LOOP.md) | interviews, journeys, a strategy question | **G0** human — a person ratifies the brief | a ratified requirement | a re-brief |
 | [`design`](loops/design/LOOP.md) | a ratified requirement | **G1** review — `council-review`'s panel | a recorded decision (ADR) | months, unwound in code |
 | [`build`](loops/build/LOOP.md) | an agreed requirement or triaged defect | **G2** mechanical — `pre-merge-review`'s gate script decides | merged code | a revert |
+| [`release`](loops/release/LOOP.md) | merged code | **G2.5** review — `launch-readiness` on evidence; **G2.6** human go/no-go | a live, reversible rollout | users and data, often irreversible |
 | [`operate`](loops/operate/LOOP.md) | a shipped service | **G3** human — the incident is closed | a postmortem and runbook deltas | live users, irreversible |
 
 Plus one **wrapper**, which is not a lifecycle stage but the two passes either side of *any* generator:
@@ -144,6 +145,41 @@ flowchart LR
 
 <!-- loop:build:end -->
 
+### `release` — merged code to live users
+
+Plan the rollout and the way back, judge readiness on evidence, draft the release notes, then a human makes the go/no-go call. The gap between a merge you can revert and a launch you often cannot.
+
+<!-- loop:release:start -->
+
+```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 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;
+
+    plan["plan<br/><small>migration-plan</small>"]:::gen
+    ready["ready<br/><small>launch-readiness</small>"]:::review
+    announce["announce<br/><small>release-notes</small>"]:::gen
+    go["go<br/><small>council-review</small>"]:::gate
+    G2_5{"G2.5 · review"}:::gate
+    G2_6{"G2.6 · human"}:::gate
+    DONE(["complete"]):::ship
+
+    plan --> ready
+    ready --> G2_5
+    G2_5 == "PROCEED" ==> announce
+    announce --> go
+    go --> G2_6
+    G2_6 == "PROCEED" ==> DONE
+
+    G2_5 -- "REVISE (max 3)" --> plan
+    G2_6 -- "REVISE (max 3)" --> plan
+```
+
+<!-- loop:release:end -->
+
 ### `operate` — a shipped service through detection and learning
 
 Instrument, write the runbook, communicate the incident, then feed the postmortem's runbook deltas straight back into the runbook. The one loop whose failures are live.
@@ -235,6 +271,7 @@ Skills for the SDLC steps around the code itself — turning raw requirements in
 | [`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. |
+| [`launch-readiness`](skills/launch-readiness/SKILL.md) | Go/no-go readiness report for a merged change before it reaches users. It lists the change's own failure modes first, then judges seven checks in order: rollback, detection, response, measured NFR targets, data & privacy, comms, staged exposure. Each row is met / not met / n/a-with-reason, with an evidence link and an owner role, and a row with no evidence is `not met`. The verdict (PROCEED / PROCEED WITH CONDITIONS / REVISE / BLOCKED) follows mechanically from the rows, and a missing rollback blocks on its own. Gaps go to `migration-plan`, `observability-plan` or `runbook-generator` instead of being drafted inline. The `ready` stage of the `release` loop. |
 
 ### Product strategy
 
@@ -308,6 +345,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 +435,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
@@ -424,7 +479,7 @@ npx skilldrop-cli install --pack dev-team --project     # .claude/skills — als
 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 loops                                 # the five loops, their stages and gates
+npx skilldrop-cli loops                                 # the six loops, their stages and gates
 npx skilldrop-cli install --loop build                  # a loop + every stage skill it sequences (RFC-0028)
 npx skilldrop-cli install --loop --pack sre-oncall      # every loop that pack declares
 npx skilldrop-cli agents                                # the reviewer subagents
@@ -448,7 +503,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 63 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/loops/release/LOOP.md

@@ -0,0 +1,76 @@
+---
+name: release
+description: Take merged code to live users through a planned, reversible rollout — plan the phases and the rollback, judge readiness on evidence, draft the release notes, then a human makes the go/no-go call. Use when the user has merged a change and asks how to roll it out, whether they are ready to launch, or for a go/no-go decision.
+---
+
+# release
+
+This loop covers the step between `build`, which ends when a human merges, and `operate`,
+which assumes the service is already live. A merge can be undone with a revert. A launch that
+has touched users or data often cannot be undone, so this loop gets its own gates instead of
+being folded into either neighbour.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `plan` | generate | [`migration-plan`](../../skills/migration-plan/SKILL.md) | — |
+| 2 | `ready` | verify | [`launch-readiness`](../../skills/launch-readiness/SKILL.md) | **G2.5** review |
+| 3 | `announce` | generate | [`release-notes`](../../skills/release-notes/SKILL.md) | — |
+| 4 | `go` | gate | [`council-review`](../../skills/council-review/SKILL.md) | **G2.6** human |
+
+## How to run this loop
+
+1. **Plan the rollout and the way back.** `migration-plan` sets out the phases, a tested
+   rollback for each one, and at most one named point of no return. For a code-only change
+   behind a flag, the plan can be short: the flag, the stages and how to turn it off. It still
+   has to exist.
+2. **Judge readiness at G2.5.** `launch-readiness` lists the change's own failure modes, then
+   checks rollback, detection, response, measured targets, data and privacy, comms and
+   exposure, each with evidence. `REVISE` returns to `plan`, and the report names which gap to
+   close and which skill closes it. A missing rollback is `BLOCKED` on its own.
+3. **Announce only once it is ready.** `release-notes` drafts the customer-facing and
+   internal notes from the git range. Writing them before G2.5 risks announcing a launch that
+   then does not happen.
+4. **A human decides at G2.6.** The release owner decides whether to ship *now*, given
+   timing, freeze windows and on-call coverage. When that decision is contested, use
+   `council-review`. `RECONSIDER` means it is ready but this is the wrong time, and the work
+   waits instead of going back to `plan`.
+
+After `PROCEED`, the change is live and the work moves to `operate`. Gaps that G2.5 sent to
+`observability-plan` or `runbook-generator` are the first things `operate` picks up.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../contracts/terminals.json). G2.5 emits `PROCEED`,
+`PROCEED WITH CONDITIONS`, `REVISE` or `BLOCKED`. G2.6 adds `RECONSIDER`. `PROCEED WITH
+CONDITIONS` at G2.5 is allowed only when the open rows are comms or exposure. A detection or
+response gap is always `REVISE`.
+
+## Non-interactive runs
+
+Never invent evidence such as rehearsal logs, load-test numbers, dashboards or sign-offs.
+When the change being released cannot be identified, emit `BLOCKED: need <the PR, tag, or
+feature name>`. G2.6 is a human gate. A headless run stops after `announce` and reports the
+G2.5 verdict for a person to act on.
+
+## When a stage's skill is not installed
+
+Name the missing skill and skilldrop as its source, do the minimal inline version of that
+stage, and record the stage as degraded. For `ready`, the minimal version is the seven checks
+written as a list, each marked met, not met or n/a with a reason. Skipping it is never the
+minimal version.
+
+## Quality bar
+
+- **Rollback exists before readiness is judged.** A plan with no way back is the one thing that cannot be fixed after launch.
+- **Readiness rests on evidence.** Every check links to something; "we're good" is `not met`.
+- **Can and should are separate gates.** G2.5 says whether it can ship; G2.6 says whether it should ship now.
+- **Detection gaps leave this loop as hand-offs.** `operate` picks them up first, rather than discovering them during the first incident.
+
+## Anti-patterns to avoid
+
+- ❌ **Jumping from merge to "instrument a running service".** That skips this loop entirely, which is the gap it exists to close.
+- ❌ **Announcing before G2.5.** Customers hear about a launch that is then pulled.
+- ❌ **Treating flag-off as a rollback without a data story.** If dual-write or a backfill has run, turning the flag off does not undo the data.
+- ❌ **Letting G2.6 overrule a G2.5 `BLOCKED`.** A human can delay a ready launch; they cannot make an unready one ready by deciding to go.

package/loops/release/loop.json

@@ -0,0 +1,47 @@
+{
+  "$comment": "RFC-0031. Covers the step between build (ends at merge, G2.1) and operate (starts at instrument). The gate ids sit between G2 and G3 to match where the loop sits in the lifecycle.",
+  "name": "release",
+  "version": "0.1.0",
+  "description": "Take merged code to live users through a planned, reversible rollout — plan the phases and the rollback, judge readiness on evidence, draft the release notes, then a human makes the go/no-go call. Use when the user has merged a change and asks how to roll it out, whether they are ready to launch, or for a go/no-go decision.",
+  "entrypoint": "LOOP.md",
+  "kind": "loop",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "plan",
+      "type": "generate",
+      "intent": "Decide the rollout phases, the rollback for each, and the one point of no return, before anything reaches users.",
+      "skills": ["migration-plan"]
+    },
+    {
+      "id": "ready",
+      "type": "verify",
+      "intent": "Judge on evidence whether the change can go live: rollback, detection, response, measured targets, data, comms, exposure.",
+      "skills": ["launch-readiness"],
+      "gate": {
+        "id": "G2.5",
+        "kind": "review",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "BLOCKED"],
+        "revise_to": "plan"
+      }
+    },
+    {
+      "id": "announce",
+      "type": "generate",
+      "intent": "Write what users and the team are told. Only after readiness, so nobody announces a launch that then fails the check.",
+      "skills": ["release-notes"]
+    },
+    {
+      "id": "go",
+      "type": "gate",
+      "intent": "A human decides whether it should ship now. Readiness says it can; this decides timing, freeze windows, and who is on call.",
+      "skills": ["council-review"],
+      "gate": {
+        "id": "G2.6",
+        "kind": "human",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "RECONSIDER", "BLOCKED"],
+        "revise_to": "plan"
+      }
+    }
+  ]
+}