skilldrop-cli 0.13.1 → 0.13.3

package/bin/skilldrop.js

@@ -3,7 +3,8 @@
  * 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.
- * Reads two catalog shapes: skilldrop (flat skills/) and agentbundle (packs/<p>/.apm/skills).
+ * Reads three catalog shapes: skilldrop pack folders (packs/<p>/pack.json + packs/<p>/skills/),
+ * flat skilldrop (skills/ + packs.json), and agentbundle (packs/<p>/pack.toml + .apm/skills).
  * Design: skilldrop-cli-design/skilldrop-cli-design.md
  * Scope:  docs/rfcs/0002-skilldrop-cli.md, docs/rfcs/0003-third-party-catalogs.md,
  *         docs/rfcs/0014-agentbundle-interop.md (the agentbundle reader)
@@ -13,6 +14,7 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const { execFileSync } = require("child_process");
+const crypto = require("crypto");
 
 const ROOT = path.resolve(__dirname, "..");
 const LEDGER = ".skilldrop.json";
@@ -35,6 +37,7 @@ const HELP = `skilldrop — portable AI-agent skills for Claude Code, Cursor, Ki
 Usage:
   skilldrop list [--from <src>]           all skills in a catalog (name, version, tier)
   skilldrop info <skill> [--from <src>]   description, related, packs, deps
+  skilldrop info --pack <name>            a pack's skills, loops, and what to try first (RFC-0032)
   skilldrop packs [--from <src>]          role-based packs
   skilldrop agents [--from <src>]         reviewer subagents in a catalog
   skilldrop loops [--from <src>]          loops — sequenced stages over skills (RFC-0028)
@@ -48,7 +51,9 @@ Usage:
                                           (--no-skills for the loop alone) (RFC-0028)
   skilldrop install --panel review        install the review panel — the 3 reviewer subagents +
                                           the pre-merge-review orchestrator that fires them (RFC-0020)
-  skilldrop update                        re-copy installed skills whose version changed
+  skilldrop update [--force]              re-copy installed skills whose version changed; files
+                                          you edited are kept and the new copy lands beside them
+                                          as <file>.upstream (--force overwrites) (RFC-0032)
   skilldrop outdated                      show installed vs current versions, change nothing
   skilldrop uninstall <skill...>          remove skills (and wiring files this tool wrote)
   skilldrop uninstall --agent <name...>   remove subagents
@@ -62,8 +67,8 @@ Usage:
 
 Catalogs:
   (default)          the catalog bundled with this package
-  --from <dir|url>   a skilldrop catalog (skills/<name>/{SKILL.md,manifest.json}) OR an
-                     agentbundle one (packs/<pack>/.apm/skills/<name>/SKILL.md); a git URL
+  --from <dir|url>   a skilldrop catalog (packs/<pack>/skills/<name>/ or flat skills/<name>/) OR
+                     an agentbundle one (packs/<pack>/.apm/skills/<name>/SKILL.md); a git URL
                      works for either — append #<branch-or-tag> to pin
 
 Install/update/uninstall targets (pick one):
@@ -104,7 +109,7 @@ 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" || a === "--panel") out.flags[a.slice(2)] = argv[++i];
+    if (a === "--pack" || a === "--ide" || a === "--dest" || a === "--from" || a === "--panel" || a === "--profile") out.flags[a.slice(2)] = argv[++i];
     else if (a.startsWith("--")) out.flags[a.slice(2)] = true;
     else out._.push(a);
   }
@@ -112,15 +117,18 @@ function parseArgs(argv) {
 }
 
 /* ---------- catalogs ----------
-   Two on-disk shapes are read (RFC-0003, RFC-0014):
-     "skilldrop" — flat skills/<name>/{SKILL.md,manifest.json} + optional packs.json
+   Three on-disk shapes are read (RFC-0003, RFC-0014, RFC-0034):
+     "packs"     — skilldrop's own layout since RFC-0034: packs/<pack>/{pack.json,
+                   skills/<name>/{SKILL.md,manifest.json}, loops/<name>/} + catalogue.json
+     "skilldrop" — flat skills/<name>/{SKILL.md,manifest.json} + optional packs.json; what
+                   skilldrop shipped before RFC-0034, and what most third-party catalogs use
      "apm"       — agentbundle (agent-ready-repo): packs/<pack>/{pack.toml,
                    .apm/skills/<name>/SKILL.md, .apm/agents/<name>.md}
    The apm reader normalizes into the same accessors the native path uses — skills keyed by
    folder name, a per-skill manifest synthesized from the SKILL.md frontmatter + the pack.toml
    version, each pack.toml's [pack] table a virtual pack — so `--from git+https://…/agent-ready-repo`
    installs his packs through this same CLI. Skill accessors: skillsIn / skillDir / skillExists /
-   manifestOf; never touch cat.skillsDir directly (it exists only on the skilldrop shape). */
+   manifestOf; never touch cat.skillsDir directly (it exists only on the flat skilldrop shape). */
 
 const catalogCache = {};
 function resolveCatalog(source) {
@@ -139,11 +147,36 @@ function resolveCatalog(source) {
     }
   }
   const src = source || BUNDLED;
+  const packsDir = path.join(dir, "packs");
+  if (fs.existsSync(packsDir) && fs.readdirSync(packsDir).some((p) => fs.existsSync(path.join(packsDir, p, "pack.json"))))
+    return (catalogCache[key] = readPacksCatalog(dir, src));
   if (fs.existsSync(path.join(dir, "skills")))
     return (catalogCache[key] = { dir, source: src, shape: "skilldrop", skillsDir: path.join(dir, "skills") });
   if (fs.existsSync(path.join(dir, "packs")))
     return (catalogCache[key] = readApmCatalog(dir, src));
-  die(`'${src}' is not a catalog — expected a skills/ (skilldrop) or packs/ (agentbundle) directory`);
+  die(`'${src}' is not a catalog — expected packs/<pack>/pack.json, a skills/ directory, or packs/<pack>/pack.toml (agentbundle)`);
+}
+
+/* RFC-0034: membership is the folder. A skill is in a pack because it sits at
+   packs/<pack>/skills/<name>/; catalogue.json only sets the order packs are listed in. */
+function readPacksCatalog(dir, source) {
+  const packsDir = path.join(dir, "packs");
+  const children = (d, marker) => fs.existsSync(d)
+    ? fs.readdirSync(d).filter((x) => fs.existsSync(path.join(d, x, marker))).sort() : [];
+  const onDisk = children(packsDir, "pack.json");
+  const idx = path.join(dir, "catalogue.json");
+  const listed = fs.existsSync(idx) ? (readJSON(idx).packs || []).filter((p) => onDisk.includes(p)) : [];
+  const order = [...listed, ...onDisk.filter((p) => !listed.includes(p))];
+  const skillIndex = {}, loopIndex = {}, packsData = {};
+  for (const pack of order) {
+    const pdir = path.join(packsDir, pack);
+    const skills = children(path.join(pdir, "skills"), "SKILL.md");
+    const loops = children(path.join(pdir, "loops"), "loop.json");
+    for (const s of skills) if (!skillIndex[s]) skillIndex[s] = { dir: path.join(pdir, "skills", s) };
+    for (const l of loops) if (!loopIndex[l]) loopIndex[l] = path.join(pdir, "loops", l);
+    packsData[pack] = Object.assign({}, readJSON(path.join(pdir, "pack.json")), { skills, loops });
+  }
+  return { dir, source, shape: "packs", skillIndex, loopIndex, packsData };
 }
 
 /* Minimal TOML read — the [pack] table's basic-string scalars (name, version, description).
@@ -205,11 +238,11 @@ function readApmCatalog(dir, source) {
 }
 
 function skillsIn(cat) {
-  if (cat.shape === "apm") return Object.keys(cat.skillIndex).sort();
+  if (cat.skillIndex) return Object.keys(cat.skillIndex).sort();
   return fs.readdirSync(cat.skillsDir).filter((d) => fs.statSync(path.join(cat.skillsDir, d)).isDirectory()).sort();
 }
 function skillDir(cat, s) {
-  if (cat.shape === "apm") return cat.skillIndex[s] && cat.skillIndex[s].dir;
+  if (cat.skillIndex) return cat.skillIndex[s] && cat.skillIndex[s].dir;
   return path.join(cat.skillsDir, s);
 }
 // Skill names reach RegExp when unwiring hooks. skillExists() proves a directory exists; it
@@ -228,7 +261,7 @@ function manifestOf(cat, s) {
     if (!cat.skillIndex[s]) throw new Error(`no such skill '${s}'`);
     return cat.skillIndex[s].manifest;
   }
-  return readJSON(path.join(cat.skillsDir, s, "manifest.json"));
+  return readJSON(path.join(skillDir(cat, s), "manifest.json"));
 }
 
 /* Agents (RFC-0012): single markdown files, frontmatter is already Claude Code's format.
@@ -260,10 +293,19 @@ function checkAgent(cat, a) {
   return problems;
 }
 function packsOf(cat) {
-  if (cat.shape === "apm") return Object.keys(cat.packsData).length ? cat.packsData : null;
+  if (cat.packsData) return Object.keys(cat.packsData).length ? cat.packsData : null;
   const p = path.join(cat.dir, "packs.json");
   return fs.existsSync(p) ? readJSON(p).packs : null;
 }
+/* RFC-0033: a pack installs together with the packs it `requires` (in practice, core), so
+   one --pack still delivers a role's whole toolkit now that shared skills have one home. */
+function packMembers(ps, name, key) {
+  const req = (ps[name].requires || []).filter((r) => ps[r]);
+  const out = [];
+  for (const n of [...req, name]) for (const x of ps[n][key] || []) if (!out.includes(x)) out.push(x);
+  if (req.length) console.log(`pack '${name}' includes ${req.join(", ")}`);
+  return out;
+}
 function profilesOf(cat) {
   const p = path.join(cat.dir, "profiles.json");
   return fs.existsSync(p) ? readJSON(p).profiles : null;
@@ -706,10 +748,10 @@ 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`);
+    if (!ps) die(`catalog '${cat.source}' defines no packs — 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();
+    return packMembers(ps, args.flags.pack, "skills");
   }
   if (!args._.length) die("nothing to install — pass skill names, --pack <name>, or --all");
   for (const s of args._) if (!skillExists(cat, s)) die(`unknown skill '${s}' in catalog '${cat.source}'`);
@@ -721,10 +763,64 @@ function copyOne(cat, s, dest, ide, l, notes) {
   fs.cpSync(skillDir(cat, s), path.join(dest, s), { recursive: true });
   const note = writeWiring(ide, dest, s, m.description);
   if (note && notes) notes.push(note);
-  l.data[s] = { version: m.version, source: cat.source };
+  l.data[s] = { version: m.version, source: cat.source, files: fileHashes(skillDir(cat, s)) };
   return m;
 }
 
+/* RFC-0032: per-file SHA-256 of a skill as the catalog shipped it, recorded in the ledger at
+   copy time. It is the baseline `update` compares against, so a file the user edited is never
+   overwritten. Paths are forward-slash relative; *.upstream files are this tool's output. */
+function sha256(buf) { return crypto.createHash("sha256").update(buf).digest("hex"); }
+function fileHashes(dir) {
+  const out = {};
+  (function walk(d, rel) {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(d, e.name), r);
+      else if (e.isFile() && !e.name.endsWith(".upstream")) out[r] = sha256(fs.readFileSync(path.join(d, e.name)));
+    }
+  })(dir, "");
+  return out;
+}
+
+/* Update one skill file by file against the ledger baseline (RFC-0032):
+     upstream unchanged            -> leave the local file alone, edited or not
+     local untouched, or new file  -> take the new version
+     local edited, upstream moved  -> keep the local file, write the new one as <file>.upstream
+   A file the catalog dropped is removed only if the user never touched it. The new baseline is
+   what the catalog ships now, so a kept edit stays "edited" until the user merges it. */
+function mergeOne(cat, s, dest, ide, l, notes) {
+  const m = manifestOf(cat, s);
+  const src = skillDir(cat, s), dst = path.join(dest, s);
+  const base = l.data[s].files, next = fileHashes(src);
+  const kept = [], orphaned = [];
+  const at = (root, rel) => path.join(root, ...rel.split("/"));
+  const localHash = (rel) => { try { return sha256(fs.readFileSync(at(dst, rel))); } catch (e) { return null; } };
+  for (const [rel, h] of Object.entries(next)) {
+    const mine = localHash(rel), to = at(dst, rel);
+    if (mine === h) { fs.rmSync(to + ".upstream", { force: true }); continue; }
+    if (h === base[rel]) continue;
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    if (mine === null ? !(rel in base) : mine === base[rel]) {
+      fs.copyFileSync(at(src, rel), to);
+      fs.rmSync(to + ".upstream", { force: true });
+    } else {
+      fs.copyFileSync(at(src, rel), to + ".upstream");
+      kept.push(rel);
+    }
+  }
+  for (const rel of Object.keys(base)) {
+    if (rel in next) continue;
+    const mine = localHash(rel);
+    if (mine === base[rel]) fs.rmSync(at(dst, rel), { force: true });
+    else if (mine !== null) orphaned.push(rel);
+  }
+  const note = writeWiring(ide, dest, s, m.description);
+  if (note && notes) notes.push(note);
+  l.data[s] = { version: m.version, source: cat.source, files: next };
+  return { m, kept, orphaned };
+}
+
 /* Install a whole review panel — the reviewer subagents + the orchestrator skill — in one
    command (RFC-0020). Needs a target with BOTH a subagent and a skill format, so it accepts
    the default (Claude Code), --project, --ide kiro, or --dest; other IDEs install the halves
@@ -854,6 +950,8 @@ function install(args) {
     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.`);
+  const pk = args.flags.pack && (packsOf(cat) || {})[args.flags.pack];
+  if (pk && pk["first-value"]) console.log("\n" + firstValueLines(pk).join("\n"));
 }
 
 function installedRows(flags) {
@@ -874,18 +972,30 @@ function installedRows(flags) {
 function update(args) {
   const { dest, ide, l, rows } = installedRows(args.flags);
   if (!rows.length) return console.log(`nothing installed at ${dest}`);
-  let n = 0;
+  let n = 0, conflicts = 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})`);
+    // No baseline (installed before RFC-0032) or --force: overwrite as before, and record one.
+    const entry = l.data[r.s];
+    if (args.flags.force || typeof entry !== "object" || !entry.files) {
+      copyOne(r.cat, r.s, dest, ide, l);
+      console.log(`updated ${r.s} ${r.installed} -> ${r.current} (${r.src})`);
+    } else {
+      const { kept, orphaned } = mergeOne(r.cat, r.s, dest, ide, l);
+      console.log(`updated ${r.s} ${r.installed} -> ${r.current} (${r.src})`);
+      for (const f of kept) console.log(`  kept your edits in ${f} — new version at ${f}.upstream`);
+      for (const f of orphaned) console.log(`  kept ${f} — dropped upstream, but you edited it`);
+      conflicts += kept.length;
+    }
     n++;
   }
   saveLedger(l);
   console.log(n ? `\n${n} skill(s) updated.` : "everything up to date.");
+  if (conflicts)
+    console.log(`${conflicts} file(s) kept your edits. Merge each <file>.upstream into its file, then delete it — or rerun with --force to take every new version.`);
 }
 
 function outdated(args) {
@@ -952,11 +1062,12 @@ function listAgents(args) {
    stages name, unless --no-skills. Optional in a catalog. */
 function loopsIn(cat) {
   if (cat.shape === "apm") return [];
+  if (cat.loopIndex) return Object.keys(cat.loopIndex).sort();
   const d = path.join(cat.dir, "loops");
   if (!fs.existsSync(d)) return [];
   return fs.readdirSync(d).filter((x) => fs.existsSync(path.join(d, x, "loop.json"))).sort();
 }
-function loopDir(cat, n) { return path.join(cat.dir, "loops", n); }
+function loopDir(cat, n) { return cat.loopIndex ? cat.loopIndex[n] : path.join(cat.dir, "loops", n); }
 function loopSpec(cat, n) { return readJSON(path.join(loopDir(cat, n), "loop.json")); }
 
 function loopSkills(cat, n) {
@@ -1010,10 +1121,10 @@ function installLoops(args) {
   let names = args._.slice();
   if (!names.length && args.flags.pack) {
     const ps = packsOf(cat);
-    if (!ps) die(`catalog '${cat.source}' has no packs.json`);
+    if (!ps) die(`catalog '${cat.source}' defines no packs`);
     const pk = ps[args.flags.pack];
     if (!pk) die(`unknown pack '${args.flags.pack}' in catalog '${cat.source}'`);
-    names = (pk.loops || []).slice();
+    names = packMembers(ps, args.flags.pack, "loops");
     if (!names.length) die(`pack '${args.flags.pack}' declares no loops`);
   }
   if (!names.length && args.flags.all) names = available.slice();
@@ -1143,9 +1254,37 @@ function list(args) {
   console.log(`\n${rows.length} skills in catalog '${cat.source}'. Details: skilldrop info <skill>`);
 }
 
+/* RFC-0032: what to try first after installing a pack, how to tell it worked, what to do
+   if it didn't — the same first-value block the pack's site page renders. */
+function firstValueLines(p) {
+  const fv = p["first-value"];
+  if (!fv) return [];
+  const out = [`Start here: ${fv["starter-task"]}`, "", `  ${fv["starter-prompt"]}`, ""];
+  for (const pre of fv.prerequisites || []) out.push(`  before you start: ${pre}`);
+  out.push(`  worked if: ${fv.verification}`, `  if nothing happens: ${fv.recovery}`);
+  return out;
+}
+
+function infoPack(args) {
+  const cat = resolveCatalog(args.flags.from);
+  const ps = packsOf(cat) || die(`catalog '${cat.source}' has no packs`);
+  const name = args.flags.pack;
+  const p = ps[name] || die(`unknown pack '${name}' — available: ${Object.keys(ps).join(", ")}`);
+  if (args.flags.json)
+    return emitJSON({ catalog: cat.source, name, ...p });
+  console.log(`${p.display_name || name}  (${name})\n\n${p.description}\n`);
+  console.log(`skills:   ${p.skills.join(", ")}`);
+  if ((p.requires || []).length) console.log(`requires: ${p.requires.join(", ")} (installed with it)`);
+  if ((p.loops || []).length) console.log(`loops:    ${p.loops.join(", ")}`);
+  if (p.links && p.links.documentation) console.log(`page:     ${p.links.documentation}`);
+  const fv = firstValueLines(p);
+  if (fv.length) console.log("\n" + fv.join("\n"));
+}
+
 function info(args) {
+  if (args.flags.pack) return infoPack(args);
   const cat = resolveCatalog(args.flags.from);
-  const s = args._[0] || die("pass a skill name");
+  const s = args._[0] || die("pass a skill name, or --pack <name>");
   if (!skillExists(cat, s)) die(`unknown skill '${s}' in catalog '${cat.source}'`);
   const m = manifestOf(cat, s);
   const ps = packsOf(cat) || {};
@@ -1182,13 +1321,13 @@ function listPacks(args) {
       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 || [],
+        name, description: p.description || null, skills: p.skills || [], requires: p.requires || [],
       })),
     });
   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(`${n.padEnd(w)}  (${p.skills.length} skills${(p.requires || []).length ? ` + ${p.requires.join(", ")}` : ""})  ${p.description}`);
   console.log("\nInstall one: skilldrop install --pack <name>");
 }
 
@@ -1205,7 +1344,7 @@ function validateCmd(args) {
   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 (!names.includes(s)) { console.log(`FAIL packs: 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.`);
 }

package/catalogue.json

@@ -0,0 +1,111 @@
+{
+  "$comment": "RFC-0034. The catalogue index: pack display order and the outcome browse axis (RFC-0026). Pack metadata lives in packs/<pack>/pack.json; membership is the folders — a skill is in a pack because it sits at packs/<pack>/skills/<name>/.",
+  "version": "1.0.0",
+  "packs": ["core", "solution-architect", "product-manager", "dev-team", "sre-oncall", "stakeholder-comms", "ai-engineering", "claude-api"],
+  "outcomes": {
+    "decide-what-to-build": {
+      "description": "Turn a direction into a committed, measurable plan: press releases, strategy frameworks, OKRs, business cases, requirements, PRDs, and the metrics that will say whether it worked.",
+      "skills": [
+        "prfaq",
+        "strategy-analysis",
+        "okr-cascade",
+        "business-case",
+        "capacity-cost-model",
+        "requirements-interview",
+        "prd-draft",
+        "nfr-spec",
+        "success-metrics",
+        "user-story-splitter",
+        "user-journey-map"
+      ]
+    },
+    "design-the-system": {
+      "description": "Commit the shape before the code: decision records, design docs, diagrams, contracts, schemas, migration and threat models, and the design of any agentic parts.",
+      "skills": [
+        "adr-generator",
+        "design-doc",
+        "architecture-diagrams",
+        "reverse-architecture",
+        "figma-diagrams",
+        "api-contract-draft",
+        "db-schema-design",
+        "data-contract",
+        "tech-comparison-matrix",
+        "threat-model",
+        "agent-threat-model",
+        "migration-plan",
+        "agent-loop-design",
+        "subagent-design",
+        "agent-budget"
+      ]
+    },
+    "build-and-review-software": {
+      "description": "The loop around the code itself: supervised implementation, adversarial review panels, test plans, triage, accessibility and static-analysis passes, and the policy files agents read.",
+      "skills": [
+        "feature-implement-loop",
+        "pre-merge-review",
+        "devils-advocate",
+        "council-review",
+        "accessibility-audit",
+        "sonar-onboard",
+        "sonar-review",
+        "test-plan-generator",
+        "bug-triage",
+        "agents-md-generator",
+        "llm-eval-harness",
+        "eval-harness-generator",
+        "contribution-wizard"
+      ]
+    },
+    "build-on-the-claude-api": {
+      "description": "Skills for teams building directly on the Anthropic API — prompt caching strategy, token budgeting, eval generation, and tool-use schema writing.",
+      "skills": [
+        "prompt-caching-advisor",
+        "token-budget-estimator",
+        "eval-harness-generator",
+        "tool-use-schema-writer"
+      ]
+    },
+    "run-and-recover-the-service": {
+      "description": "Operate what shipped: runbooks, observability design, release notes, incident communication, and the postmortem that closes the loop.",
+      "skills": [
+        "runbook-generator",
+        "observability-plan",
+        "release-notes",
+        "incident-comms",
+        "postmortem-generator",
+        "launch-readiness"
+      ]
+    },
+    "explain-it-to-decision-makers": {
+      "description": "Get a non-technical audience to a decision: audience profiling, deck outlines and real decks, exec summaries, decision logs, and how-to guides.",
+      "skills": [
+        "audience-profile",
+        "slide-outliner",
+        "deck-builder",
+        "exec-summary",
+        "decision-log",
+        "guide-builder"
+      ]
+    },
+    "govern-ai-use": {
+      "description": "Adopt AI deliberately and prove what it is doing: readiness assessment, use-case triage, rollout plans, acceptable-use policy, adoption staging, and usage reporting.",
+      "skills": [
+        "ai-readiness-assessment",
+        "ai-use-case-triage",
+        "ai-adoption-rollout",
+        "ai-usage-policy",
+        "agent-adoption-stage",
+        "ai-usage-report"
+      ]
+    },
+    "get-a-draft-ready-to-ship": {
+      "description": "The passes either side of a generator: collect a messy input into a structured brief, critique the argument, and strip the machine artifacts before it leaves the building.",
+      "skills": [
+        "brief-intake",
+        "doc-critique",
+        "output-hygiene"
+      ]
+    }
+  }
+}

package/contracts/catalogue.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/sananthanarayan/skilldrop/contracts/catalogue.schema.json",
+  "title": "skilldrop catalogue.json",
+  "$comment": "RFC-0026 / RFC-0034. The catalogue index: pack display order, and the outcome axis. Packs answer WHO needs a skill (the folder it sits in); outcomes answer WHY someone opened the catalogue.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "packs", "outcomes"],
+  "properties": {
+    "$comment": { "type": "string" },
+    "version": { "type": "string" },
+    "packs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "Every pack folder under packs/, in display order. validate.py checks both directions."
+    },
+    "outcomes": {
+      "type": "object",
+      "description": "The catalogue's second browse axis. A browse aid only — never an install unit; the CLI takes no --outcome.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["description", "skills"],
+        "properties": {
+          "description": { "type": "string", "description": "The chip's tooltip on the catalogue site." },
+          "skills": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+        }
+      }
+    }
+  }
+}

package/contracts/loop.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/sananthanarayan/skilldrop/contracts/loop.schema.json",
   "title": "skilldrop loop",
-  "$comment": "RFC-0028. A loop sequences existing skills; it never contains one. Skills stay in flat skills/<name> folders and stay independently installable — a loop is a named order plus the gates between stages. Enforced by validate.py with hand-rolled stdlib checks: skilldrop ships zero runtime dependencies and this file must not become a reason to add `jsonschema`.",
+  "$comment": "RFC-0028. A loop sequences existing skills; it never contains one. Skills stay in their own packs/<pack>/skills/<name> folders and stay independently installable — a loop is a named order plus the gates between stages. Enforced by validate.py with hand-rolled stdlib checks: skilldrop ships zero runtime dependencies and this file must not become a reason to add `jsonschema`.",
   "type": "object",
   "additionalProperties": false,
   "required": ["name", "description", "entrypoint", "kind", "stages"],
@@ -48,7 +48,7 @@
             "type": "array",
             "minItems": 1,
             "items": { "type": "string" },
-            "description": "Skill folder names, in order. Each must be a real skills/<name>. `*` means any generator, and is legal only in a wrapper."
+            "description": "Skill folder names, in order. Each must be a real skill folder (packs/<pack>/skills/<name>). `*` means any generator, and is legal only in a wrapper."
           },
           "gate": {
             "type": "object",

package/contracts/pack.schema.json

@@ -1,42 +1,49 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/sananthanarayan/skilldrop/contracts/pack.schema.json",
-  "title": "skilldrop packs.json",
-  "$comment": "RFC-0001 / RFC-0026 / RFC-0029. Packs and outcomes are METADATA ONLY — skills never move out of flat skills/<name> folders. Packs answer WHO needs a skill; outcomes answer WHY someone opened the catalogue. Both get the same two-way membership check in validate.py.",
+  "title": "skilldrop packs/<pack>/pack.json",
+  "$comment": "RFC-0001 / RFC-0032 / RFC-0033 / RFC-0034. One pack's metadata. Membership is not listed here: a skill is in this pack because it sits at packs/<pack>/skills/<name>/, and a loop because it sits at packs/<pack>/loops/<name>/. Key names follow agent-ready-repo's pack.toml so the two stay mechanically convertible.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["version", "packs", "outcomes"],
+  "required": ["description"],
   "properties": {
     "$comment": { "type": "string" },
-    "version": { "type": "string" },
-    "packs": {
+    "description": { "type": "string", "description": "One line — who this pack is for." },
+    "display_name": { "type": "string", "description": "RFC-0032. Human title for the pack's page and plugin entry." },
+    "keywords": { "type": "array", "items": { "type": "string" }, "description": "RFC-0032. Search terms, copied into the plugin entry." },
+    "links": {
       "type": "object",
-      "description": "Role-based bundles. Keys are pack names.",
-      "additionalProperties": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["description", "skills"],
-        "properties": {
-          "description": { "type": "string", "description": "One line — who this pack is for." },
-          "skills": { "type": "array", "items": { "type": "string" }, "minItems": 1,
-                      "description": "Real skill folders. Every skill must appear in at least one pack." },
-          "loops": { "type": "array", "items": { "type": "string" },
-                     "description": "RFC-0028. Real loops/ folders. Every loop must appear in at least one pack." }
-        }
+      "additionalProperties": false,
+      "description": "RFC-0032. Catalogue-facing links; `documentation` is the pack's page.",
+      "properties": {
+        "homepage": { "type": "string" },
+        "repository": { "type": "string" },
+        "documentation": { "type": "string" }
       }
     },
-    "outcomes": {
+    "maintainers": {
+      "type": "array",
+      "description": "RFC-0032.",
+      "items": { "type": "object", "additionalProperties": false, "required": ["name"], "properties": { "name": { "type": "string" } } }
+    },
+    "first-value": {
       "type": "object",
-      "description": "The catalogue's second browse axis. A browse aid only — never an install unit; the CLI takes no --outcome.",
-      "additionalProperties": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["description", "skills"],
-        "properties": {
-          "description": { "type": "string", "description": "The chip's tooltip on the catalogue site." },
-          "skills": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
-        }
+      "additionalProperties": false,
+      "description": "RFC-0032. What to try first after installing, how to tell it worked, and what to do if it didn't. Key names match agent-ready-repo's [pack.first-value].",
+      "required": ["audience-posture", "prerequisites", "starter-task", "starter-prompt", "verification", "recovery"],
+      "properties": {
+        "audience-posture": { "type": "string", "enum": ["technical", "non-technical"] },
+        "prerequisites": { "type": "array", "items": { "type": "string" } },
+        "starter-task": { "type": "string" },
+        "starter-prompt": { "type": "string" },
+        "verification": { "type": "string" },
+        "recovery": { "type": "string" }
       }
+    },
+    "requires": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "RFC-0033. Packs installed together with this one (in practice, `core`). One level only: a required pack may not itself require."
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "Portable AI-agent skills for the deliverables knowledge workers ship \u2014 diagrams, ADRs, PRDs, runbooks, decks, reviews \u2014 installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",
@@ -11,11 +11,10 @@
   },
   "files": [
     "bin/",
-    "skills/",
+    "packs/",
     "agents/",
-    "loops/",
     "contracts/",
-    "packs.json",
+    "catalogue.json",
     "model-routing.json"
   ],
   "engines": {