skilldrop-cli 0.2.0

package/bin/skilldrop.js

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+/* skilldrop — install portable AI-agent skills into Claude Code, Cursor, Kiro,
+ * or any directory, from the bundled catalog or any third-party catalog
+ * (--from <path | git-url[#ref]>). Zero dependencies; copy-only, never executes
+ * catalog content at install time.
+ * Design: skilldrop-cli-design/skilldrop-cli-design.md
+ * Scope:  docs/rfcs/0002-skilldrop-cli.md, docs/rfcs/0003-third-party-catalogs.md
+ */
+"use strict";
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execFileSync } = require("child_process");
+
+const ROOT = path.resolve(__dirname, "..");
+const LEDGER = ".skilldrop.json";
+const BUNDLED = "bundled";
+
+const HELP = `skilldrop — portable AI-agent skills for Claude Code, Cursor, Kiro, and more
+
+Usage:
+  skilldrop list [--from <src>]           all skills in a catalog (name, version, tier)
+  skilldrop info <skill> [--from <src>]   description, related, packs, deps
+  skilldrop packs [--from <src>]          role-based packs
+  skilldrop install <skill...>            install skills (default: Claude Code, user scope)
+  skilldrop install --pack <name>         install a whole pack
+  skilldrop install --all                 install every skill in the catalog
+  skilldrop update                        re-copy installed skills whose version changed
+  skilldrop outdated                      show installed vs current versions, change nothing
+  skilldrop uninstall <skill...>          remove skills (and wiring files this tool wrote)
+  skilldrop validate [--from <src>]       structural check of a catalog (for catalog authors)
+
+Catalogs:
+  (default)          the catalog bundled with this package
+  --from <dir>       any local directory shaped like skills/<name>/{SKILL.md,manifest.json}
+  --from <git-url>   any git repo with that shape; append #<branch-or-tag> to pin
+
+Install/update/uninstall targets (pick one):
+  (default)          ~/.claude/skills           Claude Code, user scope
+  --project          ./.claude/skills           Claude Code, project scope
+  --ide cursor       ./.cursor/skills           + writes .cursor/rules/<skill>.mdc
+  --ide kiro         ./.kiro/skills             + writes .kiro/steering/<skill>.md
+  --dest <dir>       any directory              Codex / Continue / Cline / Aider (wiring tips printed)
+
+Options:
+  --with-related     also install each skill's related companions (one level)
+`;
+
+function die(msg) { console.error("error: " + msg); process.exit(1); }
+function readJSON(p) { return JSON.parse(fs.readFileSync(p, "utf8")); }
+
+function parseArgs(argv) {
+  const out = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--pack" || a === "--ide" || a === "--dest" || a === "--from") out.flags[a.slice(2)] = argv[++i];
+    else if (a.startsWith("--")) out.flags[a.slice(2)] = true;
+    else out._.push(a);
+  }
+  return out;
+}
+
+/* ---------- catalogs ---------- */
+
+const catalogCache = {};
+function resolveCatalog(source) {
+  const key = source || BUNDLED;
+  if (catalogCache[key]) return catalogCache[key];
+  let dir;
+  if (!source) dir = ROOT;
+  else if (fs.existsSync(source)) dir = path.resolve(source);
+  else {
+    const [url, ref] = source.split("#");
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "skilldrop-cat-"));
+    try {
+      execFileSync("git", ["clone", "--depth", "1", ...(ref ? ["--branch", ref] : []), url, dir], { stdio: ["ignore", "ignore", "pipe"] });
+    } catch (e) {
+      die(`could not fetch catalog '${source}' — not a local path, and git clone failed`);
+    }
+  }
+  const skillsDir = path.join(dir, "skills");
+  if (!fs.existsSync(skillsDir)) die(`'${source || dir}' is not a skilldrop catalog — no skills/ directory`);
+  return (catalogCache[key] = { dir, skillsDir, source: source || BUNDLED });
+}
+function skillsIn(cat) {
+  return fs.readdirSync(cat.skillsDir).filter((d) => fs.statSync(path.join(cat.skillsDir, d)).isDirectory()).sort();
+}
+function manifestOf(cat, s) { return readJSON(path.join(cat.skillsDir, s, "manifest.json")); }
+function packsOf(cat) {
+  const p = path.join(cat.dir, "packs.json");
+  return fs.existsSync(p) ? readJSON(p).packs : null;
+}
+
+/* Structural gate (RFC-0003): a skill must pass before it is copied anywhere. */
+function checkSkill(cat, s) {
+  const problems = [];
+  const dir = path.join(cat.skillsDir, s);
+  if (!fs.existsSync(path.join(dir, "SKILL.md"))) problems.push("SKILL.md missing");
+  let m = null;
+  try { m = manifestOf(cat, s); } catch (e) { problems.push("manifest.json missing or invalid JSON"); }
+  if (m) {
+    if (m.name !== s) problems.push(`manifest name '${m.name}' != folder '${s}'`);
+    if (!m.description) problems.push("manifest missing description");
+    if (!m.version) problems.push("manifest missing version");
+    if (!m.model || !m.model.tier) problems.push("manifest missing model.tier");
+    const fmName = (() => {
+      try {
+        const fm = fs.readFileSync(path.join(dir, "SKILL.md"), "utf8").split("---")[1] || "";
+        const match = fm.match(/^name:\s*(\S+)/m);
+        return match && match[1];
+      } catch (e) { return null; }
+    })();
+    if (fmName && fmName !== s) problems.push(`SKILL.md frontmatter name '${fmName}' != folder '${s}'`);
+  }
+  return problems;
+}
+function gate(cat, names) {
+  let bad = 0;
+  for (const s of names) {
+    const problems = checkSkill(cat, s);
+    for (const p of problems) console.error(`refused ${s}: ${p}`);
+    if (problems.length) bad++;
+  }
+  if (bad) die(`${bad} skill(s) failed the structural check — nothing was installed`);
+}
+
+/* ---------- install targets & ledger ---------- */
+
+function target(flags) {
+  if (flags.dest) return { dest: path.resolve(flags.dest), ide: "generic" };
+  const ide = flags.ide || "claude";
+  if (ide === "claude")
+    return flags.project
+      ? { dest: path.resolve(".claude", "skills"), ide }
+      : { dest: path.join(os.homedir(), ".claude", "skills"), ide };
+  if (ide === "cursor") return { dest: path.resolve(".cursor", "skills"), ide };
+  if (ide === "kiro") return { dest: path.resolve(".kiro", "skills"), ide };
+  die(`unknown --ide '${ide}' (claude | cursor | kiro; use --dest for anything else)`);
+}
+
+function ledger(dest) {
+  const p = path.join(dest, LEDGER);
+  return { path: p, data: fs.existsSync(p) ? readJSON(p) : {} };
+}
+function saveLedger(l) { fs.writeFileSync(l.path, JSON.stringify(l.data, null, 2) + "\n"); }
+/* Ledger values: {version, source}; legacy plain strings mean a bundled install. */
+function lver(v) { return typeof v === "string" ? v : v.version; }
+function lsrc(v) { return typeof v === "string" ? BUNDLED : v.source || BUNDLED; }
+
+function wiringPath(ide, dest, s) {
+  const base = path.dirname(dest); // .cursor/ or .kiro/
+  if (ide === "cursor") return path.join(base, "rules", `${s}.mdc`);
+  if (ide === "kiro") return path.join(base, "steering", `${s}.md`);
+  return null;
+}
+function writeWiring(ide, dest, s, desc) {
+  const p = wiringPath(ide, dest, s);
+  if (!p) return;
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  if (ide === "cursor")
+    fs.writeFileSync(p, `---\ndescription: ${desc.replace(/\n/g, " ")}\nglobs:\nalwaysApply: false\n---\nFollow the instructions in .cursor/skills/${s}/SKILL.md when the user requests this task.\n`);
+  else
+    fs.writeFileSync(p, `When the user requests the following, defer to the instructions in .kiro/skills/${s}/SKILL.md:\n\n${desc}\n`);
+}
+
+/* ---------- commands ---------- */
+
+function expandNames(args, cat) {
+  if (args.flags.all) return skillsIn(cat);
+  if (args.flags.pack) {
+    const ps = packsOf(cat);
+    if (!ps) die(`catalog '${cat.source}' has no packs.json — install skills by name`);
+    const p = ps[args.flags.pack];
+    if (!p) die(`unknown pack '${args.flags.pack}' in catalog '${cat.source}'`);
+    return p.skills.slice();
+  }
+  if (!args._.length) die("nothing to install — pass skill names, --pack <name>, or --all");
+  for (const s of args._) if (!fs.existsSync(path.join(cat.skillsDir, s))) die(`unknown skill '${s}' in catalog '${cat.source}'`);
+  return args._.slice();
+}
+
+function copyOne(cat, s, dest, ide, l) {
+  const m = manifestOf(cat, s);
+  fs.cpSync(path.join(cat.skillsDir, s), path.join(dest, s), { recursive: true });
+  writeWiring(ide, dest, s, m.description);
+  l.data[s] = { version: m.version, source: cat.source };
+  return m;
+}
+
+function install(args) {
+  const cat = resolveCatalog(args.flags.from);
+  let names = expandNames(args, cat);
+  if (args.flags["with-related"]) {
+    const seen = new Set(names);
+    for (const s of names.slice()) {
+      let related = [];
+      try { related = manifestOf(cat, s).related || []; } catch (e) { /* gated below */ }
+      for (const r of related) if (!seen.has(r) && fs.existsSync(path.join(cat.skillsDir, r))) { seen.add(r); names.push(r); }
+    }
+  }
+  gate(cat, names);
+  const { dest, ide } = target(args.flags);
+  fs.mkdirSync(dest, { recursive: true });
+  const l = ledger(dest);
+  const pipDeps = [], suggestions = new Set();
+  for (const s of names) {
+    const m = copyOne(cat, s, dest, ide, l);
+    if (fs.existsSync(path.join(cat.skillsDir, s, "requirements.txt"))) pipDeps.push(s);
+    for (const r of m.related || []) if (!names.includes(r) && !l.data[r]) suggestions.add(r);
+    console.log(`installed ${s}@${m.version} -> ${dest}`);
+  }
+  saveLedger(l);
+  console.log(`\n${names.length} skill(s) installed (${ide}).`);
+  if (cat.source !== BUNDLED)
+    console.log(`\nWARNING: third-party catalog '${cat.source}'. Skills are instructions your AI agent will follow — review each installed SKILL.md under ${dest} before first use. Install copied files only; nothing was executed.`);
+  if (ide === "generic")
+    console.log("wiring: attach each skill's SKILL.md to your agent (Continue/Cline: @file, Aider: /add, Codex: reference it from AGENTS.md) — see the repo README's per-IDE steps.");
+  for (const s of pipDeps)
+    console.log(`deps: ${s} needs Python packages — run: cd ${path.join(dest, s)} && python3 -m pip install -r requirements.txt`);
+  if (suggestions.size)
+    console.log(`related (not installed): ${[...suggestions].sort().join(", ")} — add --with-related or install by name.`);
+}
+
+function installedRows(flags) {
+  const { dest, ide } = target(flags);
+  const l = ledger(dest);
+  const rows = Object.keys(l.data).sort().map((s) => {
+    const src = lsrc(l.data[s]);
+    let current = null, cat = null;
+    try {
+      cat = resolveCatalog(src === BUNDLED ? undefined : src);
+      if (fs.existsSync(path.join(cat.skillsDir, s))) current = manifestOf(cat, s).version;
+    } catch (e) { /* unreachable source: current stays null */ }
+    return { s, src, cat, installed: lver(l.data[s]), current };
+  });
+  return { dest, ide, l, rows };
+}
+
+function update(args) {
+  const { dest, ide, l, rows } = installedRows(args.flags);
+  if (!rows.length) return console.log(`nothing installed at ${dest}`);
+  let n = 0;
+  for (const r of rows) {
+    if (!r.current) { console.log(`skip ${r.s}: source '${r.src}' unreachable or skill gone from it`); continue; }
+    if (r.current === r.installed) continue;
+    const problems = checkSkill(r.cat, r.s);
+    if (problems.length) { console.log(`skip ${r.s}: fails structural check in '${r.src}' (${problems[0]})`); continue; }
+    copyOne(r.cat, r.s, dest, ide, l);
+    console.log(`updated ${r.s} ${r.installed} -> ${r.current} (${r.src})`);
+    n++;
+  }
+  saveLedger(l);
+  console.log(n ? `\n${n} skill(s) updated.` : "everything up to date.");
+}
+
+function outdated(args) {
+  const { dest, rows } = installedRows(args.flags);
+  if (!rows.length) return console.log(`nothing installed at ${dest}`);
+  const stale = rows.filter((r) => r.current && r.current !== r.installed);
+  for (const r of stale) console.log(`${r.s}: installed ${r.installed}, current ${r.current} (${r.src})`);
+  console.log(stale.length ? `\n${stale.length} outdated — run: skilldrop update` : "everything up to date.");
+}
+
+function uninstall(args) {
+  if (!args._.length) die("pass skill names to uninstall");
+  const { dest, ide } = target(args.flags);
+  const l = ledger(dest);
+  for (const s of args._) {
+    fs.rmSync(path.join(dest, s), { recursive: true, force: true });
+    const w = wiringPath(ide, dest, s);
+    if (w) fs.rmSync(w, { force: true });
+    delete l.data[s];
+    console.log(`removed ${s} from ${dest}`);
+  }
+  saveLedger(l);
+}
+
+function list(args) {
+  const cat = resolveCatalog(args.flags.from);
+  const rows = skillsIn(cat).map((s) => {
+    try { const m = manifestOf(cat, s); return [s, m.version || "?", (m.model && m.model.tier) || "?"]; }
+    catch (e) { return [s, "?", "?"]; }
+  });
+  const w = Math.max(...rows.map((r) => r[0].length));
+  for (const [s, v, t] of rows) console.log(`${s.padEnd(w)}  ${v}  ${t}`);
+  console.log(`\n${rows.length} skills in catalog '${cat.source}'. Details: skilldrop info <skill>`);
+}
+
+function info(args) {
+  const cat = resolveCatalog(args.flags.from);
+  const s = args._[0] || die("pass a skill name");
+  if (!fs.existsSync(path.join(cat.skillsDir, s))) die(`unknown skill '${s}' in catalog '${cat.source}'`);
+  const m = manifestOf(cat, s);
+  const ps = packsOf(cat) || {};
+  const inPacks = Object.entries(ps).filter(([, p]) => p.skills.includes(s)).map(([n]) => n);
+  console.log(`${m.name}@${m.version}  (tier: ${m.model && m.model.tier})\n\n${m.description}\n`);
+  console.log(`catalog: ${cat.source}`);
+  console.log(`packs:   ${inPacks.join(", ") || "-"}`);
+  console.log(`related: ${(m.related || []).join(", ") || "-"}`);
+  if (((m.deps || {}).pip || []).length || fs.existsSync(path.join(cat.skillsDir, s, "requirements.txt")))
+    console.log("deps:    python (requirements.txt)");
+  if (((m.env || {}).required || []).length) console.log(`env:     ${m.env.required.join(", ")} (required)`);
+}
+
+function listPacks(args) {
+  const cat = resolveCatalog(args.flags.from);
+  const ps = packsOf(cat);
+  if (!ps) return console.log(`catalog '${cat.source}' defines no packs.`);
+  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.skills.length} skills)  ${p.description}`);
+  console.log("\nInstall one: skilldrop install --pack <name>");
+}
+
+function validateCmd(args) {
+  const cat = resolveCatalog(args.flags.from);
+  const names = skillsIn(cat);
+  let bad = 0;
+  for (const s of names) {
+    const problems = checkSkill(cat, s);
+    for (const p of problems) console.log(`FAIL ${s}: ${p}`);
+    if (problems.length) bad++;
+  }
+  const ps = packsOf(cat);
+  if (ps)
+    for (const [n, p] of Object.entries(ps))
+      for (const s of p.skills)
+        if (!names.includes(s)) { console.log(`FAIL packs.json: pack '${n}' lists unknown skill '${s}'`); bad++; }
+  if (bad) { console.log(`\n${bad} problem(s) in catalog '${cat.source}'.`); process.exit(1); }
+  console.log(`OK: ${names.length} skills in catalog '${cat.source}' pass the structural check.`);
+}
+
+const args = parseArgs(process.argv.slice(2));
+const cmd = args._.shift();
+const commands = { list, info, packs: listPacks, install, update, outdated, uninstall, validate: validateCmd };
+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

@@ -0,0 +1,147 @@
+{
+  "$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.",
+  "version": "0.2.0",
+  "active_provider": "claude-code",
+  "tiers": {
+    "light": {
+      "use_for": "Mechanical mapping, extraction, and lookup against a fixed rubric. Deterministic enough that a small/cheap model matches a large one.",
+      "relative_cost": 1
+    },
+    "standard": {
+      "use_for": "Most generation. Synthesizing a structured artifact from a brief, where quality matters but the reasoning is not adversarial. The default tier.",
+      "relative_cost": 4
+    },
+    "heavy": {
+      "use_for": "Adversarial reasoning and weighted judgment, where a cheaper model demonstrably misses edge cases, under-calls severity, or mis-weights tradeoffs. Spend here only when the hard thinking IS the value.",
+      "relative_cost": 20
+    }
+  },
+  "providers": {
+    "claude-code": {
+      "label": "Claude Code (Anthropic)",
+      "models": {
+        "light": "claude-haiku-4-5-20251001",
+        "standard": "claude-sonnet-4-6",
+        "heavy": "claude-opus-4-8"
+      },
+      "select_via": "`/model <model-id>` in the session, or hand the skill to the model-router agent for automatic dispatch.",
+      "automation": ".claude/agents/model-router.md"
+    },
+    "cursor": {
+      "label": "Cursor",
+      "models": {
+        "light": "<your cheapest capable model, e.g. a small Claude/GPT/Gemini>",
+        "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.",
+      "automation": null,
+      "note": "Cursor exposes whatever models your plan enables (Claude, GPT, Gemini). Fill in the three you actually use."
+    },
+    "openai-codex": {
+      "label": "OpenAI Codex CLI",
+      "models": {
+        "light": "<your cheapest OpenAI model>",
+        "standard": "<your default OpenAI model>",
+        "heavy": "<your most capable OpenAI model>"
+      },
+      "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."
+    },
+    "kiro": {
+      "label": "Kiro",
+      "models": {
+        "light": "<your cheapest capable model>",
+        "standard": "<your default model>",
+        "heavy": "<your most capable model>"
+      },
+      "select_via": "Select the model in Kiro's model picker, or pin it in the custom-agent / steering definition that loads the skill.",
+      "automation": null
+    },
+    "generic": {
+      "label": "Any other tool",
+      "models": {
+        "light": "<your cheapest capable model>",
+        "standard": "<your default model>",
+        "heavy": "<your most capable model>"
+      },
+      "select_via": "However your tool selects a model. The tier tells you which of your three to pick.",
+      "automation": null
+    }
+  },
+  "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.",
+      "type": "heuristic_no_llm"
+    },
+    {
+      "id": "reasoning-floor",
+      "rule": "Never downgrade a skill whose tier is 'heavy'. These are the reasoning skills; downgrading defeats their purpose. The router may upgrade but never demote below the skill's declared tier.",
+      "type": "hard_constraint"
+    },
+    {
+      "id": "ambiguous-input",
+      "rule": "Escalate one tier when the input is contradictory, underspecified, or the user explicitly asks for the most rigorous output ('be thorough', 'this is going to the board'). Do NOT escalate just because the topic sounds important.",
+      "type": "heuristic_no_llm"
+    },
+    {
+      "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.",
+      "type": "heuristic_no_llm"
+    },
+    {
+      "id": "user-override",
+      "rule": "An explicit user model choice always wins. The router reports what it would have picked, then honors the override.",
+      "type": "hard_constraint"
+    }
+  ],
+  "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": "Generates pptx content + runs a script. Content shaping, 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." },
+    "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." },
+    "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." },
+    "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." }
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "skilldrop-cli",
+  "version": "0.2.0",
+  "description": "Portable AI-agent skills for the deliverables knowledge workers ship — diagrams, ADRs, PRDs, runbooks, decks, reviews — installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
+  "bin": {
+    "skilldrop": "bin/skilldrop.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "packs.json",
+    "model-routing.json"
+  ],
+  "engines": {
+    "node": ">=16.7.0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "cursor",
+    "kiro",
+    "codex",
+    "ai-agent",
+    "skills",
+    "prompts",
+    "adr",
+    "prd",
+    "runbook",
+    "diagrams"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sananthanarayan/skilldrop.git"
+  },
+  "license": "MIT"
+}

package/packs.json

@@ -0,0 +1,90 @@
+{
+  "$comment": "Virtual skill packs — role-based bundles for one-command install. Packs are METADATA ONLY: skills stay in flat skills/<name> folders (golden rule: skills are discovered by path), a skill may belong to several packs, and every skill must belong to at least one (validate.py enforces both directions). Install a pack with `python3 pack.py <pack> --install`; see README. Rationale: docs/rfcs/0001-skill-packs.md.",
+  "version": "0.1.0",
+  "packs": {
+    "solution-architect": {
+      "description": "Design-phase artifacts: diagrams, decision records, design docs, contracts, schemas, threat models, and the reviews that gate them.",
+      "skills": [
+        "brief-intake",
+        "architecture-diagrams",
+        "reverse-architecture",
+        "figma-diagrams",
+        "adr-generator",
+        "design-doc",
+        "tech-comparison-matrix",
+        "threat-model",
+        "api-contract-draft",
+        "data-contract",
+        "db-schema-design",
+        "nfr-spec",
+        "capacity-cost-model",
+        "council-review",
+        "doc-critique"
+      ]
+    },
+    "product-manager": {
+      "description": "Direction to requirements: PR/FAQs, strategy frameworks, OKRs, PRDs, journey maps, story splitting, and success measurement.",
+      "skills": [
+        "brief-intake",
+        "prfaq",
+        "strategy-analysis",
+        "okr-cascade",
+        "business-case",
+        "requirements-interview",
+        "prd-draft",
+        "user-journey-map",
+        "user-story-splitter",
+        "success-metrics",
+        "exec-summary",
+        "doc-critique"
+      ]
+    },
+    "dev-team": {
+      "description": "Build-and-ship loop: story implementation with adversarial review, test plans, triage, migrations, release notes, and code-quality gates.",
+      "skills": [
+        "user-story-splitter",
+        "feature-implement-loop",
+        "devils-advocate",
+        "council-review",
+        "test-plan-generator",
+        "bug-triage",
+        "migration-plan",
+        "release-notes",
+        "sonar-onboard",
+        "sonar-review",
+        "accessibility-audit"
+      ]
+    },
+    "sre-oncall": {
+      "description": "Operate the service: runbooks, observability design, incident communications, postmortems, and capacity/cost models.",
+      "skills": [
+        "runbook-generator",
+        "observability-plan",
+        "incident-comms",
+        "postmortem-generator",
+        "capacity-cost-model"
+      ]
+    },
+    "stakeholder-comms": {
+      "description": "Non-technical audiences: audience profiling, deck outlines and real .pptx decks, exec summaries, decision logs, and guides.",
+      "skills": [
+        "brief-intake",
+        "audience-profile",
+        "slide-outliner",
+        "deck-builder",
+        "exec-summary",
+        "decision-log",
+        "guide-builder",
+        "doc-critique"
+      ]
+    },
+    "ai-engineering": {
+      "description": "Ship and measure AI features: eval harness design, AI-usage reporting, and the data contracts AI pipelines depend on.",
+      "skills": [
+        "llm-eval-harness",
+        "ai-usage-report",
+        "data-contract"
+      ]
+    }
+  }
+}