skilldrop-cli 0.9.0 → 0.9.2

package/README.md

@@ -3,9 +3,9 @@
 [![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 51 skills, filterable by pack, tag, and model tier.
+**[Browse the catalogue →](https://sananthanarayan.github.io/skilldrop/)** — all 55 skills, filterable by pack, tag, and model tier.
 
-**51 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:
+**55 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,
@@ -160,6 +160,10 @@ Designing the agentic systems themselves — the loops, orchestrations, and budg
 
 | Skill | What it does |
 |---|---|
+| [`ai-readiness-assessment`](skills/ai-readiness-assessment/SKILL.md) | Score readiness to adopt AI across **six fixed dimensions** — data, tooling, skills, governance, process, culture — each 0–4 with a **one-line evidence reference**, or `[insufficient evidence]` rather than a guessed middle number. Gaps are ranked by **what blocks first**, not by lowest score, with the dependency named ("Skills can't move until Tooling ≥ 2"), and each carries a first action and an owner *role*. Ends with a posture sentence that takes a position and names what would change it — never a bare maturity label, because "you are Level 2 of 5" is not something a leader can fund. |
+| [`ai-use-case-triage`](skills/ai-use-case-triage/SKILL.md) | Rank candidate AI use cases on value × feasibility × risk with the **weights shown** (default 40/35/25). Each candidate is restated as *a workflow and a person*, never a technology; feasibility asks whether the output can be **verified before it matters**, not whether a model can produce it. Produces a recommended first slice with an **observable kill condition** and a time box, plus a mandatory **not-yet list** where every rejection carries the condition that would promote it. A portfolio with no rejections hasn't triaged anything. |
+| [`ai-adoption-rollout`](skills/ai-adoption-rollout/SKILL.md) | Plan the **human** rollout (the counterpart to `migration-plan`'s technical one) — cohorts smallest-first with a reason each is next, per-cohort hands-on enablement built from what the pilot actually got stuck on, champions as roles **with protected hours**, and an adoption **gate per wave** (observable + threshold + bake time + rollback). The comms plan must state explicitly **what will not change** about headcount and evaluation; silence there is read as bad news and is the biggest driver of quiet non-adoption. Licences activated is not adoption. |
+| [`ai-usage-policy`](skills/ai-usage-policy/SKILL.md) | Draft the organisation-wide acceptable-use policy — **three** data tiers (five aren't memorable at the moment of pasting) with concrete examples from *this* org, permitted/prohibited uses stated as behaviours, and a human-review matrix keyed to **consequence** rather than to model names that age out in months. Every prohibition names a permitted alternative, because a ban with no sanctioned path moves the work to personal accounts where you can't see it — and there's always an exception route with a turnaround time. |
 | [`ai-usage-report`](skills/ai-usage-report/SKILL.md) | Turn a CSV/JSONL of AI usage events (exported from an MCP server or other telemetry source) into a per-user, team-rollup, or effectiveness-focused report. Surfaces volume, breadth, session depth, and — where the data supports it — whether AI outputs were actually consumed in shipped artifacts vs generated and discarded (the "AI theater" question). Refuses to generate an aggregate rollup for teams smaller than 5 to preserve anonymity. |
 | [`llm-eval-harness`](skills/llm-eval-harness/SKILL.md) | Design the **dev-loop quality gate** for an LLM-powered feature (prompt, RAG, agent, classifier) — so prompt and model changes ship on numbers, not vibes. A versioned golden set in three deliberate buckets (representative from real logs, adversarial/edge, and regression cases frozen from every past failure); the **cheapest adequate grading method per case** (programmatic → structured assertions → LLM-as-judge only when quality is genuinely subjective, and then validated against human labels with bias controls); a metric matched to the task with **both gates set before the first run** (no-regression + critical-subset-at-100%); a failure taxonomy that points iteration at the biggest bucket; and cost/latency tracked beside quality. Enforces the held-out split and the no-tuning-on-test rule. Provider-neutral. |
 
@@ -264,6 +268,7 @@ npx skilldrop-cli install --agent devils-advocate       # -> ~/.claude/agents/ (
 npx skilldrop-cli install --panel review                # the whole review fleet: 3 subagents + the pre-merge-review orchestrator (RFC-0020)
 npx skilldrop-cli outdated && npx skilldrop-cli update  # skills improve; cp -R never tells you
 npx skilldrop-cli list | skilldrop info <skill> | skilldrop packs | skilldrop uninstall <skill>
+npx skilldrop-cli list --json                            # machine-readable: list/info/packs/agents/outdated (RFC-0021)
 ```
 
 `--with-related` also pulls each skill's companions. From a clone (or before the package is published): `node bin/skilldrop.js <same args>`. Scope and design: [RFC-0002](docs/rfcs/0002-skilldrop-cli.md), full command surface in [`docs/designs/skilldrop-cli-design.md`](docs/designs/skilldrop-cli-design.md).

package/bin/skilldrop.js

@@ -48,6 +48,9 @@ Usage:
   skilldrop uninstall <skill...>          remove skills (and wiring files this tool wrote)
   skilldrop uninstall --agent <name...>   remove subagents
   skilldrop validate [--from <src>]       structural check of a catalog (for catalog authors)
+  skilldrop scan [<skill...>] [--from <src>]  supply-chain scan — flag network/exec/credential
+                                          patterns in scripts and injection-shaped instructions
+                                          in SKILL.md before you trust a catalog (RFC-0022)
 
 Catalogs:
   (default)          the catalog bundled with this package
@@ -72,6 +75,8 @@ Options:
                        --ide antigravity  ~/.gemini/config/agents  markdown, subagent: true
                        --dest <dir>   any directory         copied as-is
                      Cursor has no agent format — use a custom mode (agents/README.md).
+  --json             machine-readable output for list | info | packs | agents | outdated —
+                     one JSON object on stdout, nothing else (for agents, scripts, CI)
   --with-related     also install each skill's related companions (one level)
   --with-hooks       also wire any hooks a skill declares (RFC-0006) — git pre-commit
                      reminders and Claude Code session-start context; degrades where the
@@ -82,6 +87,11 @@ Options:
 function die(msg) { console.error("error: " + msg); process.exit(1); }
 function readJSON(p) { return JSON.parse(fs.readFileSync(p, "utf8")); }
 
+/* --json (RFC-0021): the read commands emit one machine-readable object on stdout and nothing
+   else, so an agent or script can consume them without scraping aligned columns. Human output is
+   unchanged by default — this is additive. Errors still go to stderr and exit non-zero. */
+function emitJSON(obj) { console.log(JSON.stringify(obj, null, 2)); }
+
 function parseArgs(argv) {
   const out = { _: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {
@@ -276,6 +286,117 @@ function gate(cat, names) {
   if (bad) die(`${bad} skill(s) failed the structural check — nothing was installed`);
 }
 
+/* ---------- supply-chain scan (RFC-0022) ----------
+   A skill is instruction prose an agent will obey, and its scripts are code that runs on the
+   user's machine — so installing a third-party catalog is a supply-chain event. Anthropic's own
+   Skills guidance says to audit a skill's files for "unexpected network calls, file access
+   patterns, or operations that don't match the Skill's stated purpose"; this automates that first
+   pass. It is a HEURISTIC that reports — it never blocks and never replaces reading the skill.
+
+   Two rule sets, deliberately different:
+   - SCRIPT_RULES run over executable files (real code): network, exec, credential, obfuscation.
+   - PROSE_RULES run over SKILL.md and only match *instructions to misbehave* — not security
+     vocabulary, so a skill that legitimately discusses injection (threat-model) isn't flagged. */
+
+const SCRIPT_EXT = new Set([".py", ".js", ".mjs", ".cjs", ".sh", ".bash", ".zsh", ".rb", ".pl", ".ps1"]);
+
+const SCRIPT_RULES = [
+  { id: "exec-remote", sev: "🟥", why: "downloads and executes remote content — the classic supply-chain payload",
+    re: /(curl|wget)[^\n|]*\|\s*(sudo\s+)?(ba|z|)sh|eval\s*\(\s*(requests|urllib|fetch)|base64\s+(-d|--decode)[^\n|]*\|\s*(ba|z|)sh/i },
+  { id: "shell-exec", sev: "🟧", why: "executes shell commands",
+    re: /\b(os\.system|subprocess\.(run|call|Popen|check_output)|child_process|execSync|spawnSync|shell_exec|`[^`\n]*\$\()/ },
+  { id: "network", sev: "🟧", why: "makes outbound network calls",
+    re: /\b(requests\.(get|post|put)|urllib\.request|httpx\.|axios\.|node-fetch|\bfetch\s*\(\s*["'`]https?:|curl\s+https?:|wget\s+https?:)/i },
+  { id: "credentials", sev: "🟧", why: "reads credentials or secret material",
+    re: /\b(os\.environ|process\.env)\b[^\n]{0,40}(TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL)|~\/\.(aws|ssh|npmrc|netrc)|\.env\b|id_rsa/i },
+  { id: "broad-fs", sev: "🟨", why: "writes outside the skill's own directory",
+    re: /\b(shutil\.rmtree|rm\s+-rf\s+[~/]|open\s*\(\s*["'`]\/(etc|usr|bin)|fs\.(unlink|rmSync)\s*\([^)]*\.\.\/)/ },
+];
+
+const PROSE_RULES = [
+  { id: "instruction-override", sev: "🟥", why: "tells the agent to ignore its prior instructions",
+    re: /ignore\s+(all\s+)?(previous|prior|earlier|above|preceding)\s+(instructions|prompts|rules)/i },
+  { id: "conceal-from-user", sev: "🟥", why: "tells the agent to hide actions from the user",
+    re: /(do\s*n[o']?t|never|without)\s+(tell|telling|inform|informing|notify|notifying|mention|mentioning)\s+(the\s+)?(user|human)/i },
+  { id: "memory-overwrite", sev: "🟥", why: "instructs the agent to rewrite its own persistent memory/identity",
+    re: /(update|overwrite|append\s+to|modify)\s+your\s+(own\s+)?(SOUL|MEMORY|CLAUDE|AGENTS)\.md/i },
+  { id: "prose-exfil", sev: "🟧", why: "instructs the agent to send data to an external endpoint",
+    re: /\b(POST|send|upload|transmit)\b[^\n.]{0,60}\bto\s+https?:\/\//i },
+];
+
+function walkFiles(dir, out = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walkFiles(p, out);
+    else out.push(p);
+  }
+  return out;
+}
+
+/* Scan one skill. Returns [{sev, id, why, file, line, text}] — worst first. */
+function scanSkill(cat, s) {
+  const dir = skillDir(cat, s);
+  const findings = [];
+  if (!dir || !fs.existsSync(dir)) return findings;
+  for (const file of walkFiles(dir)) {
+    const rel = path.relative(dir, file);
+    const ext = path.extname(file).toLowerCase();
+    const isScript = SCRIPT_EXT.has(ext);
+    const isProse = path.basename(file) === "SKILL.md";
+    if (!isScript && !isProse) continue;
+    let body = "";
+    try { body = fs.readFileSync(file, "utf8"); } catch (e) { continue; }
+    const rules = isScript ? SCRIPT_RULES : PROSE_RULES;
+    body.split(/\r?\n/).forEach((line, i) => {
+      if (line.length > 400) return; // minified/data line — not reviewable prose or code
+      for (const r of rules) {
+        if (r.re.test(line))
+          findings.push({ sev: r.sev, id: r.id, why: r.why, file: rel, line: i + 1, text: line.trim().slice(0, 120) });
+      }
+    });
+  }
+  const order = { "🟥": 0, "🟧": 1, "🟨": 2, "⚪": 3 };
+  return findings.sort((a, b) => order[a.sev] - order[b.sev]);
+}
+
+function printScan(cat, names, { compact = false } = {}) {
+  let total = 0, worst = null;
+  for (const s of names) {
+    const f = scanSkill(cat, s);
+    if (!f.length) continue;
+    total += f.length;
+    if (!worst || f[0].sev === "🟥") worst = worst === "🟥" ? worst : f[0].sev;
+    console.log(`\n${s}`);
+    for (const x of (compact ? f.slice(0, 3) : f))
+      console.log(`  ${x.sev} ${x.id} — ${x.why}\n     ${x.file}:${x.line}  ${x.text}`);
+    if (compact && f.length > 3) console.log(`     … ${f.length - 3} more (skilldrop scan ${s} --from ${cat.source})`);
+  }
+  return { total, worst };
+}
+
+function scan(args) {
+  const cat = resolveCatalog(args.flags.from);
+  const names = args._.length ? args._.slice() : skillsIn(cat);
+  for (const s of names) if (!skillExists(cat, s)) die(`unknown skill '${s}' in catalog '${cat.source}'`);
+
+  if (args.flags.json) {
+    const out = names.map((s) => ({ skill: s, findings: scanSkill(cat, s) })).filter((r) => r.findings.length);
+    return emitJSON({
+      catalog: cat.source, scanned: names.length,
+      flagged: out.length, findingCount: out.reduce((n, r) => n + r.findings.length, 0), skills: out,
+    });
+  }
+  console.log(`Scanning ${names.length} skill(s) in catalog '${cat.source}' for supply-chain patterns…`);
+  const { total } = printScan(cat, names);
+  if (!total) {
+    console.log("\nNo flagged patterns found.");
+  } else {
+    console.log(`\n${total} flagged pattern(s). These are HEURISTICS, not verdicts — a match can be` +
+                ` entirely legitimate (a skill that is *about* security, or a script that genuinely needs the network).`);
+    console.log("Read the cited lines before installing. Nothing here is executed by skilldrop; installs copy files only.");
+  }
+}
+
 /* ---------- install targets & ledger ---------- */
 
 function target(flags) {
@@ -643,8 +764,15 @@ function install(args) {
     console.log(`\n${withHooks.join(", ")} declare hooks — re-run with --with-hooks to wire them (git pre-commit reminders / session-start context).`);
   }
 
-  if (cat.source !== BUNDLED)
+  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.`);
+    // Supply-chain scan (RFC-0022): surface risky patterns at the moment of trust. Reports only —
+    // the files are already copied, and a match is a prompt to read, not a verdict.
+    const { total } = printScan(cat, names, { compact: true });
+    console.log(total
+      ? `\n${total} pattern(s) worth reading before you trust these skills. Full detail: skilldrop scan --from ${cat.source}`
+      : "\nSupply-chain scan: no flagged patterns.");
+  }
   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)
@@ -687,8 +815,18 @@ function update(args) {
 
 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);
+  if (args.flags.json)
+    return emitJSON({
+      dest,
+      count: rows.length,
+      outdatedCount: stale.length,
+      skills: rows.map((r) => ({
+        name: r.s, installed: r.installed, current: r.current,
+        source: r.src, outdated: !!(r.current && r.current !== r.installed),
+      })),
+    });
+  if (!rows.length) return console.log(`nothing installed at ${dest}`);
   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.");
 }
@@ -712,6 +850,15 @@ function uninstall(args) {
 function listAgents(args) {
   const cat = resolveCatalog(args.flags.from);
   const names = agentsIn(cat);
+  if (args.flags.json)
+    return emitJSON({
+      catalog: cat.source,
+      count: names.length,
+      agents: names.map((a) => {
+        const m = agentMeta(cat, a);
+        return { name: a, description: m.description || null, tools: m.tools || null, model: m.model || null };
+      }),
+    });
   if (!names.length) return console.log(`catalog '${cat.source}' ships no agents.`);
   const w = Math.max(...names.map((n) => n.length));
   for (const a of names) {
@@ -779,6 +926,12 @@ function list(args) {
     try { const m = manifestOf(cat, s); return [s, m.version || "?", (m.model && m.model.tier) || "?"]; }
     catch (e) { return [s, "?", "?"]; }
   });
+  if (args.flags.json)
+    return emitJSON({
+      catalog: cat.source,
+      count: rows.length,
+      skills: rows.map(([name, version, tier]) => ({ name, version, tier })),
+    });
   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>`);
@@ -791,6 +944,21 @@ function info(args) {
   const m = manifestOf(cat, s);
   const ps = packsOf(cat) || {};
   const inPacks = Object.entries(ps).filter(([, p]) => p.skills.includes(s)).map(([n]) => n);
+  const needsPip = ((m.deps || {}).pip || []).length > 0 || fs.existsSync(path.join(skillDir(cat, s), "requirements.txt"));
+  if (args.flags.json)
+    return emitJSON({
+      catalog: cat.source,
+      name: m.name,
+      version: m.version || null,
+      description: m.description || null,
+      tier: (m.model && m.model.tier) || null,
+      packs: inPacks,
+      related: m.related || [],
+      tags: m.tags || [],
+      deps: { pip: (m.deps || {}).pip || [], npm: (m.deps || {}).npm || [], requirementsTxt: needsPip },
+      env: { required: (m.env || {}).required || [], optional: (m.env || {}).optional || [] },
+      hooks: m.hooks || [],
+    });
   console.log(`${m.name}@${m.version}  (tier: ${(m.model && m.model.tier) || "n/a"})\n\n${m.description}\n`);
   console.log(`catalog: ${cat.source}`);
   console.log(`packs:   ${inPacks.join(", ") || "-"}`);
@@ -803,6 +971,14 @@ function info(args) {
 function listPacks(args) {
   const cat = resolveCatalog(args.flags.from);
   const ps = packsOf(cat);
+  if (args.flags.json)
+    return emitJSON({
+      catalog: cat.source,
+      count: ps ? Object.keys(ps).length : 0,
+      packs: Object.entries(ps || {}).map(([name, p]) => ({
+        name, description: p.description || null, skills: p.skills || [],
+      })),
+    });
   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))
@@ -830,7 +1006,7 @@ function validateCmd(args) {
 
 const args = parseArgs(process.argv.slice(2));
 const cmd = args._.shift();
-const commands = { list, info, packs: listPacks, agents: listAgents, install, update, outdated, uninstall, validate: validateCmd };
+const commands = { list, info, packs: listPacks, agents: listAgents, install, update, outdated, uninstall, validate: validateCmd, scan };
 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

@@ -114,6 +114,10 @@
     "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." },
+    "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." },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.9.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.",
+  "version": "0.9.2",
+  "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.",
   "author": {
     "name": "Sanjay Ananthanarayan",
     "url": "https://github.com/sananthanarayan"

package/packs.json

@@ -38,7 +38,8 @@
         "user-story-splitter",
         "success-metrics",
         "exec-summary",
-        "doc-critique"
+        "doc-critique",
+        "ai-use-case-triage"
       ]
     },
     "dev-team": {
@@ -83,7 +84,7 @@
       ]
     },
     "ai-engineering": {
-      "description": "Build and run AI systems: agent loop design, subagent orchestration, spend budgets, agent security review, eval harnesses, AI-usage reporting, and the data contracts AI pipelines depend on.",
+      "description": "Adopt and build AI systems: readiness assessment, use-case triage, rollout and acceptable-use policy, plus agent loop design, subagent orchestration, spend budgets, agent security review, eval harnesses, AI-usage reporting, and the data contracts AI pipelines depend on.",
       "skills": [
         "agent-loop-design",
         "subagent-design",
@@ -91,7 +92,11 @@
         "agent-threat-model",
         "llm-eval-harness",
         "ai-usage-report",
-        "data-contract"
+        "data-contract",
+        "ai-readiness-assessment",
+        "ai-use-case-triage",
+        "ai-adoption-rollout",
+        "ai-usage-policy"
       ]
     }
   }

package/skills/adr-generator/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Write an ADR for this decision",
+    "should_trigger": true
+  },
+  {
+    "query": "Document the 'we decided X because Y' moment as an architecture decision record",
+    "should_trigger": true
+  },
+  {
+    "query": "Capture this architectural decision in MADR format",
+    "should_trigger": true
+  },
+  {
+    "query": "We picked Postgres over Dynamo — record the decision properly",
+    "should_trigger": true
+  },
+  {
+    "query": "Extract the decisions and owners from these meeting notes",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a full engineering design doc for this feature",
+    "should_trigger": false
+  },
+  {
+    "query": "Critique the ADR I already wrote",
+    "should_trigger": false
+  },
+  {
+    "query": "Convene a council to decide which database we should use",
+    "should_trigger": false
+  }
+]

package/skills/adr-generator/evals/evals.json

@@ -0,0 +1,17 @@
+{
+  "skill_name": "adr-generator",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write an ADR: we decided to use Postgres as our primary datastore instead of DynamoDB, because our access patterns are relational and the team already operates Postgres.",
+      "assertions": [
+        "Status is one of Proposed / Accepted / Deprecated / Superseded by ADR-NNNN, defaulting to Proposed unless the user says it was agreed",
+        "Title is a noun phrase naming the decision, not a verb phrase naming the activity",
+        "Consequences include real trade-offs and downsides, not only upsides",
+        "The alternatives considered each carry a why-not, not just a description",
+        "The chosen format is MADR by default; Nygard only when explicitly requested",
+        "No invented context — facts not supplied by the user are marked rather than fabricated"
+      ]
+    }
+  ]
+}

package/skills/ai-adoption-rollout/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ai-adoption-rollout
+description: Plan the human rollout of an AI tool or workflow to an organisation — sized cohorts, enablement per cohort, named champions, a comms plan that states what will not change, and an adoption gate every wave must pass before the next one opens. Use when a tool has been chosen and the question is how it reaches people without stalling or backlash. Do NOT use to phase a technical cutover (that's migration-plan) or to choose which use case to roll out (that's ai-use-case-triage).
+---
+
+# ai-adoption-rollout
+
+The tool is chosen; the risk now is **people**. This plans the human rollout: who gets it when, what they're taught, who they ask, what they're told, and the observable that must hold before the next cohort opens.
+
+Rollouts fail quietly. Licences get assigned, a launch email goes out, usage spikes for a week and decays, and nobody can say which step failed. Every wave here carries a gate so that decay is visible while it's still fixable.
+
+## How to respond
+
+1. **Restate what's being rolled out, to whom, and the adoption outcome.** Not "increase AI usage" — a behaviour: "support agents draft first responses with assistance on the top 3 categories". Usage is a proxy; the behaviour is the goal. Cap clarifying questions at 2.
+
+2. **Design cohorts, smallest first.** Default three waves — **pilot** (5–15 volunteers, highest tolerance) → **early** (one whole team or function, includes sceptics) → **general**. Each cohort names who is in it and *why they're next*: the pilot proves the workflow, the early wave proves it survives people who didn't ask for it. Skipping straight to general is the most common failure and this skill refuses it.
+
+3. **Specify enablement per cohort, not one training deck.** What each cohort must be able to *do* before they're counted as enabled — a 30-minute hands-on with their own real task beats an hour of slides. Name the format, the time cost, and who delivers it. Later cohorts get shorter enablement built from what the pilot actually got stuck on.
+
+4. **Name champions by role, with a time budget.** One per cohort, with hours protected. An unbudgeted champion is a volunteer who quietly stops answering. State what they own: first-line questions, collecting friction, running the office hour.
+
+5. **Write the comms plan — including what will not change.** Three messages: the announcement (what, why, what's in it for the reader), the reassurance (**explicitly: whether this affects headcount, evaluation, or how work is judged**), and the follow-up. Silence on the reassurance point is read as bad news and is the single biggest driver of quiet non-adoption.
+
+6. **Put an adoption gate on every wave.** Observable, with a threshold and a bake time, before the next cohort opens. ✅ "≥60% of the pilot used it on a real task in week 2, and no unresolved 🟥 issue in the friction log — hold 1 week." A gate that is "the pilot went well" is not a gate. Each wave also names its **rollback**: what happens if the gate fails — extend, narrow, or stop.
+
+7. **Name the friction loop.** Where friction is captured, who triages it weekly, and how a fix reaches the next cohort. A rollout with no feedback path teaches the organisation that complaints go nowhere.
+
+## Quality bar
+
+- **Cohorts get smaller-to-larger with a stated reason each**, and the plan refuses a single big-bang wave.
+- **Every wave has an adoption gate with an observable, a threshold, and a bake time** — plus a rollback if it fails.
+- **The outcome is a behaviour, not a usage number.** Licences activated is not adoption.
+- **The comms plan states explicitly what will not change** (headcount, evaluation, how work is judged). Omitting it is a defect, not a tone choice.
+- **Champions are roles with protected hours**, never names, and never unbudgeted.
+- **Enablement is per cohort and hands-on with the participant's own work** — a single deck for everyone is the failure mode.
+- **The friction loop names an owner and a cadence.**
+
+## When to use this skill
+
+- ✅ A tool or AI workflow is chosen and now has to reach real people.
+- ✅ A previous rollout decayed after launch and you're planning the retry.
+- ✅ Leadership wants a timeline with checkpoints rather than a launch date.
+
+## When NOT to use this skill
+
+- ❌ Phasing a *technical* cutover (schema, API version, datastore) — that's `migration-plan`, which sequences systems, not people.
+- ❌ Choosing which use case to roll out — that's [`ai-use-case-triage`](../ai-use-case-triage/SKILL.md).
+- ❌ Deciding whether the organisation is ready at all — that's [`ai-readiness-assessment`](../ai-readiness-assessment/SKILL.md).
+- ❌ Writing the rules for what may be put into the tool — that's [`ai-usage-policy`](../ai-usage-policy/SKILL.md).
+- ❌ Reporting on adoption that already happened — that's `ai-usage-report`.
+
+## Anti-patterns to avoid
+
+- ❌ **Big-bang rollout.** Everyone at once means no cohort to learn from and no way to stop. The gate structure exists to prevent exactly this.
+- ❌ **Counting licences as adoption.** Seats assigned, logins, "activated users" — all measure procurement, not behaviour change.
+- ❌ **A launch email as the comms plan.** One announcement with no reassurance and no follow-up is how a rollout gets read as a threat.
+- ❌ **Champions with no time.** Naming an enthusiastic person and adding nothing to their calendar is delegation of blame.
+- ❌ **Training everyone identically.** The pilot's stumbling blocks should shorten the next cohort's enablement; if the deck never changes, nobody was listening.
+- ❌ **A gate with no rollback.** "Proceed if it goes well" is not a decision rule — say what happens when it doesn't.
+
+**Non-interactive:** with no user to ask, derive cohorts from the stated org size and tag them `[assumption]`. If the input names no tool or workflow to roll out — only a wish to "drive AI adoption" — emit `BLOCKED: need the specific tool or workflow being rolled out and the population it reaches`.

package/skills/ai-adoption-rollout/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Plan how we roll this AI tool out to the org",
+    "should_trigger": true
+  },
+  {
+    "query": "How do we drive adoption without a backlash?",
+    "should_trigger": true
+  },
+  {
+    "query": "Design the cohorts and enablement for our AI launch",
+    "should_trigger": true
+  },
+  {
+    "query": "Our last AI rollout decayed after launch — plan the retry",
+    "should_trigger": true
+  },
+  {
+    "query": "Plan the phased migration of our database schema",
+    "should_trigger": false
+  },
+  {
+    "query": "Which use case should we roll out first?",
+    "should_trigger": false
+  },
+  {
+    "query": "Write the rules for what people can put into these tools",
+    "should_trigger": false
+  },
+  {
+    "query": "Report on how much AI our team is using",
+    "should_trigger": false
+  }
+]

package/skills/ai-adoption-rollout/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "ai-adoption-rollout",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We've picked an AI assistant for our 300-person support org. Plan the rollout.",
+      "assertions": [
+        "Cohorts are sized smallest-first (pilot, early, general) with a stated reason each cohort is next",
+        "A single big-bang wave is explicitly refused",
+        "Every wave has an adoption gate with an observable, a threshold, and a bake time, plus a rollback if the gate fails",
+        "The adoption outcome is stated as a behaviour rather than a usage or licence number",
+        "The comms plan explicitly states what will not change regarding headcount, evaluation, or how work is judged",
+        "Champions are named as roles with protected hours",
+        "Enablement differs per cohort and is hands-on with the participant's own work",
+        "A friction loop names an owner and a cadence"
+      ]
+    }
+  ]
+}

package/skills/ai-adoption-rollout/manifest.json

@@ -0,0 +1,33 @@
+{
+  "name": "ai-adoption-rollout",
+  "version": "0.1.0",
+  "description": "Plan the human rollout of an AI tool or workflow to an organisation — sized cohorts, enablement per cohort, named champions, a comms plan that states what will not change, and an adoption gate every wave must pass before the next one opens. Use when a tool has been chosen and the question is how it reaches people without stalling or backlash. Do NOT use to phase a technical cutover (that's migration-plan) or to choose which use case to roll out (that's ai-use-case-triage).",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "ai-readiness-assessment",
+    "ai-usage-policy",
+    "ai-usage-report",
+    "ai-use-case-triage",
+    "migration-plan"
+  ],
+  "tags": [
+    "ai-adoption",
+    "rollout",
+    "change-management",
+    "enablement",
+    "cohorts",
+    "comms"
+  ],
+  "model": {
+    "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."
+  }
+}

package/skills/ai-readiness-assessment/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: ai-readiness-assessment
+description: Score an organisation's or team's readiness to adopt AI tooling across six gating dimensions — data, tooling, skills, governance, process, and culture — with an evidence line per score and the blocking gaps ranked by what stops adoption first. Use when the user asks "are we ready for AI", wants an AI maturity or readiness baseline, or needs to know what to fix before rolling tools out. Do NOT use to pick which use cases to build (that's ai-use-case-triage) or to plan the rollout itself (that's ai-adoption-rollout).
+---
+
+# ai-readiness-assessment
+
+Produce a **baseline a leadership team can act on**: where the organisation actually stands on the six things that gate AI adoption, what the evidence is for each score, and which gaps block adoption *first*. The output is a scored table plus a ranked gap list — not a maturity label and not a slide.
+
+Readiness assessments fail in one of two ways: a number with no evidence behind it, or a diagnosis with no next action. This skill refuses both.
+
+## How to respond
+
+1. **Establish scope and the decision it feeds.** Whose readiness — one team, a function, the whole company? And what happens with the answer (a go/no-go, a budget request, a sequencing decision)? Scope changes what counts as evidence. Cap clarifying questions at 2.
+
+2. **Score the six dimensions.** These are fixed — do not invent new ones for a single engagement, and do not drop one because it's awkward to assess. Score each **0–4** (0 absent · 1 ad hoc · 2 repeatable · 3 managed · 4 optimised):
+
+   | Dimension | The question it answers |
+   |---|---|
+   | **Data** | Is the material these tools need reachable, current, and permitted to be used? |
+   | **Tooling** | Are licences, access, and environments actually in people's hands? |
+   | **Skills** | Can people write a decent prompt, judge an output, and know when not to trust it? |
+   | **Governance** | Is there a rule for what may be put in, and a named owner for it? |
+   | **Process** | Does the workflow have a place for a machine draft plus a human review gate? |
+   | **Culture** | Is the incentive to use it, or to hide that it was used? |
+
+3. **Attach evidence to every score.** One line naming what you observed — a system, a document, a stated practice, a number. A score with no evidence line is deleted, not softened. Where the input doesn't support a score, emit `[insufficient evidence: <what to collect>]` rather than guessing a middle number.
+
+4. **Rank the gaps by what blocks first, not by what scores lowest.** A 1 in Governance that blocks every use case outranks a 0 in Culture that blocks nothing yet. Name the dependency: "Skills cannot move until Tooling ≥ 2 — people can't practise on access they don't have."
+
+5. **Give each gap a first action and an owner role.** Concrete and small enough to start this quarter. ❌ "Improve data governance." ✅ "Name a data owner for the three systems in scope and publish an allowed-use tier for each — legal + platform lead, 2 weeks."
+
+6. **State the overall posture in one sentence, and what would change it.** ✅ "Ready for a bounded pilot in engineering; not ready for company-wide rollout until Governance reaches 2." Never a bare maturity label.
+
+## Quality bar
+
+- **Every score carries an evidence line.** A number with nothing behind it is the failure mode this skill exists to prevent — cut it or mark it `[insufficient evidence]`.
+- **All six dimensions appear**, including the ones the input is thin on. Silence on a dimension reads as a pass, and that's how readiness reports mislead.
+- **Gaps are ranked by blocking order, not by score.** The lowest number is not automatically the first problem, and the plan must say why.
+- **Every gap has a first action and an owner role** — a role, never a person's name, so the assessment doesn't go stale when someone changes teams.
+- **The posture sentence takes a position** and names the condition that would change it. "It depends" is a refusal to do the job.
+- **No invented facts.** Where the input is silent, say so; a fabricated observation is worse than an admitted gap.
+
+## When to use this skill
+
+- ✅ "Are we ready to roll out AI tooling?" — before committing budget or a timeline.
+- ✅ Establishing a baseline to re-measure against in two quarters.
+- ✅ A leadership team disagrees about whether the blocker is tools, skills, or policy.
+
+## When NOT to use this skill
+
+- ❌ Choosing *which* workflows to automate — that's [`ai-use-case-triage`](../ai-use-case-triage/SKILL.md).
+- ❌ Planning the rollout once you've decided to go — that's [`ai-adoption-rollout`](../ai-adoption-rollout/SKILL.md).
+- ❌ Writing the rules for what people may put into a tool — that's [`ai-usage-policy`](../ai-usage-policy/SKILL.md).
+- ❌ A market or competitive question ("should we enter this space?") — that's `strategy-analysis`.
+- ❌ Measuring adoption that has already happened — that's `ai-usage-report`.
+
+## Anti-patterns to avoid
+
+- ❌ **A maturity label as the deliverable.** "You are Level 2 of 5" tells a leader nothing they can fund. The ranked gap list is the product; the score is just its index.
+- ❌ **Scoring what's easy to score.** Tooling is countable, Culture is not — and a report that goes deep on licences and hand-waves incentives has measured the wrong thing.
+- ❌ **Middle scores as a hedge.** A 2 everywhere means the assessment refused to commit. If the evidence is thin, say `[insufficient evidence]` and name what to collect.
+- ❌ **Gaps with no owner.** An unowned action is a wish. Roles, not names.
+- ❌ **Recommending tools.** This assesses readiness; vendor selection is a different decision (`tech-comparison-matrix`) and mixing them lets a vendor pitch masquerade as a diagnosis.
+
+**Non-interactive:** with no user to ask, derive the scope from the input and tag it `[assumption]`. If the input contains no observable evidence for any dimension — a request with no organisational context — emit `BLOCKED: need observable context (systems, current practice, or stated policy) for at least three dimensions` rather than scoring from imagination.