rsc-universal 0.1.1

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "rsc-universal",
+  "version": "0.1.1",
+  "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
+  "type": "module",
+  "bin": {
+    "rsc": "scripts/rsc.js",
+    "rsc-install": "scripts/install-apply.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "manifest": "node scripts/build-manifest.js",
+    "manifest:check": "node scripts/build-manifest.js --check",
+    "validate": "node scripts/build-manifest.js --validate",
+    "test": "node --test",
+    "coverage": "c8 --reporter=text node --test",
+    "prepublishOnly": "npm run manifest && npm run validate"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "ajv": "^8.18.0",
+    "sql.js": "^1.14.1"
+  },
+  "devDependencies": {
+    "c8": "^10.1.3"
+  },
+  "files": [
+    "scripts",
+    "targets",
+    "schema",
+    "skills",
+    "manifest.json"
+  ],
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "cli",
+    "skills",
+    "ai"
+  ],
+  "license": "MIT",
+  "author": "Eric Risco",
+  "homepage": "https://github.com/ericrisco/skills#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ericrisco/skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ericrisco/skills/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schema/frontmatter.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["name", "description", "tags"],
+  "properties": {
+    "name": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+    "description": { "type": "string", "minLength": 10 },
+    "tags": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "recommends": { "type": "array", "items": { "type": "string" } },
+    "profiles": { "type": "array", "items": { "enum": ["minimal", "core", "full"] } }
+  }
+}

package/scripts/build-manifest.js

@@ -0,0 +1,72 @@
+import { readdirSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv from 'ajv';
+import { parseFrontmatter } from './lib/frontmatter.js';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const SKILLS = join(ROOT, 'skills');
+
+function skillDirs() {
+  return readdirSync(SKILLS).filter((d) => {
+    try {
+      return statSync(join(SKILLS, d)).isDirectory() && statSync(join(SKILLS, d, 'SKILL.md')).isFile();
+    } catch {
+      return false;
+    }
+  });
+}
+
+export function buildManifest() {
+  const version = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
+  const ids = skillDirs();
+  const known = new Set(ids);
+  const skills = ids.map((id) => {
+    const fm = parseFrontmatter(readFileSync(join(SKILLS, id, 'SKILL.md'), 'utf8'));
+    return {
+      id,
+      description: fm.description,
+      tags: fm.tags || [],
+      recommends: (fm.recommends || []).filter((r) => known.has(r)),
+      profiles: fm.profiles || [],
+    };
+  }).sort((a, b) => a.id.localeCompare(b.id));
+  return { version, counts: { skills: skills.length }, skills };
+}
+
+export function validateFrontmatter() {
+  const ajv = new Ajv({ allErrors: true });
+  const schema = JSON.parse(readFileSync(join(ROOT, 'schema/frontmatter.schema.json'), 'utf8'));
+  const validate = ajv.compile(schema);
+  const ids = skillDirs();
+  const errors = [];
+  for (const id of ids) {
+    const fm = parseFrontmatter(readFileSync(join(SKILLS, id, 'SKILL.md'), 'utf8'));
+    if (!validate(fm)) errors.push(`${id}: ${ajv.errorsText(validate.errors)}`);
+  }
+  return errors;
+}
+
+function main() {
+  const arg = process.argv[2];
+  const out = join(ROOT, 'manifest.json');
+  if (arg === '--validate') {
+    const errs = validateFrontmatter();
+    if (errs.length) { console.error(errs.join('\n')); process.exit(1); }
+    console.log('frontmatter OK');
+    return;
+  }
+  const manifest = buildManifest();
+  const json = JSON.stringify(manifest, null, 2) + '\n';
+  if (arg === '--check') {
+    let current = '';
+    try { current = readFileSync(out, 'utf8'); } catch { /* missing */ }
+    if (current !== json) { console.error('manifest.json is stale — run `npm run manifest`'); process.exit(1); }
+    console.log(`manifest OK (${manifest.counts.skills} skills)`);
+    return;
+  }
+  writeFileSync(out, json);
+  console.log(`wrote manifest.json (${manifest.counts.skills} skills)`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();

package/scripts/consult.js

@@ -0,0 +1,106 @@
+import initSqlJs from 'sql.js';
+
+// Stopwords (es + en) — these match everywhere via LIKE and drown the signal.
+const STOP = new Set([
+  'una', 'un', 'unos', 'unas', 'con', 'de', 'del', 'la', 'el', 'los', 'las', 'para',
+  'que', 'porque', 'en', 'mi', 'mis', 'me', 'quiero', 'tener', 'hacer', 'al', 'lo',
+  'su', 'sus', 'este', 'esta', 'esto', 'como', 'mas', 'más', 'algo', 'cosa', 'cosas',
+  'the', 'and', 'or', 'to', 'of', 'in', 'for', 'with', 'my', 'want', 'build', 'it',
+  'need', 'have', 'make', 'create', 'add', 'new',
+]);
+
+// Spanish / colloquial terms → catalog tags. Lets non-programmers describe
+// outcomes in their words and still hit the right (English-tagged) skill.
+const SYNONYMS = {
+  web: ['web', 'frontend'], pagina: ['web'], 'página': ['web'], landing: ['landing', 'web'],
+  tienda: ['web', 'frontend'], ecommerce: ['web'], pagos: ['security', 'auth'], pago: ['security'],
+  datos: ['database', 'sql'], base: ['database'], guardar: ['database'], almacenar: ['database'],
+  publicar: ['deploy', 'docker'], publicarla: ['deploy'], publicarlo: ['deploy'], online: ['deploy'],
+  desplegar: ['deploy'], deploy: ['deploy'], servidor: ['backend', 'deploy'],
+  empresa: ['company', 'harness'], negocio: ['company', 'harness'], documentar: ['docs', 'wiki', 'harness'],
+  documenta: ['docs', 'harness'], documentacion: ['docs', 'harness'], 'documentación': ['docs', 'harness'],
+  conectar: ['connect', 'harness'], conecta: ['connect', 'harness'], herramientas: ['tools', 'harness'],
+  procesos: ['ops', 'harness'], ops: ['ops', 'harness'], conocimiento: ['knowledge', 'wiki', 'harness'],
+  app: ['mobile', 'app'], aplicacion: ['app'], 'aplicación': ['app'], movil: ['mobile'], 'móvil': ['mobile'],
+  api: ['api', 'backend'], backend: ['backend'], rest: ['api'],
+  seguro: ['security'], seguridad: ['security'], login: ['auth', 'security'], auth: ['auth'],
+  agente: ['agents', 'ai'], agentes: ['agents'], ia: ['ai', 'agents'], llm: ['llm', 'agents'],
+  presentacion: ['presentations'], 'presentación': ['presentations'], diapositivas: ['slides'],
+  curso: ['course', 'teaching'], 'enseñar': ['teaching'], ensenar: ['teaching'],
+  marketing: ['marketing'], copy: ['copywriting'], texto: ['copywriting'], textos: ['copywriting'],
+};
+
+function expandedTerms(query) {
+  const raw = query.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ').split(/\s+/)
+    .filter((t) => t.length > 1 && !STOP.has(t));
+  const set = new Set();
+  for (const t of raw) {
+    set.add(t);
+    for (const syn of SYNONYMS[t] || []) set.add(syn);
+  }
+  return [...set];
+}
+
+export async function rank(manifest, query) {
+  const terms = expandedTerms(query);
+  if (!terms.length) return [];
+  const scored = scoreRows(manifest.skills, terms);
+  const SQL = await initSqlJs();
+  const db = new SQL.Database();
+
+  const rows = manifest.skills.map((sk) => [
+    sk.id,
+    ` ${sk.id} ${sk.description} ${(sk.tags || []).join(' ')} `.toLowerCase(),
+  ]);
+
+  // Prefer FTS5 for fidelity with ECC; fall back to scored whole-word LIKE if
+  // the sql.js wasm build was compiled without the FTS5 module.
+  try {
+    db.run('CREATE VIRTUAL TABLE s USING fts5(id, doc);');
+    const stmt = db.prepare('INSERT INTO s (id, doc) VALUES (?, ?)');
+    for (const r of rows) stmt.run(r);
+    stmt.free();
+    const match = terms.map((t) => `"${t}"*`).join(' OR ');
+    const res = db.exec('SELECT id FROM s WHERE s MATCH ? ORDER BY rank', [match]);
+    db.close();
+    if (!res.length) return [];
+    const ids = new Set(res[0].values.map(([id]) => id));
+    return scored.filter((r) => ids.has(r.id)).sort(byScore);
+  } catch {
+    db.run('CREATE TABLE s (id TEXT, doc TEXT);');
+    const stmt = db.prepare('INSERT INTO s (id, doc) VALUES (?, ?)');
+    for (const r of rows) stmt.run(r);
+    stmt.free();
+    // Whole-word match: pad doc with spaces and look for "% term %".
+    const score = terms.map(() => '(doc LIKE ?)').join(' + ');
+    const params = terms.map((t) => `% ${t} %`);
+    const res = db.exec(
+      `SELECT id, (${score}) AS score FROM s WHERE score > 0 ORDER BY score DESC, id`,
+      params,
+    );
+    db.close();
+    if (!res.length) return [];
+    const ids = new Set(res[0].values.map(([id]) => id));
+    return scored.filter((r) => ids.has(r.id)).sort(byScore);
+  }
+}
+
+function scoreRows(skills, terms) {
+  return skills.map((skill) => {
+    const id = skill.id.toLowerCase();
+    const tags = (skill.tags || []).map((t) => t.toLowerCase());
+    const description = ` ${skill.description.toLowerCase()} `;
+    let score = 0;
+    for (const term of terms) {
+      if (id === term) score += 20;
+      else if (id.includes(term)) score += 8;
+      if (tags.includes(term)) score += 10;
+      if (description.includes(` ${term} `)) score += 1;
+    }
+    return { id: skill.id, score };
+  }).filter((r) => r.score > 0);
+}
+
+function byScore(a, b) {
+  return b.score - a.score || a.id.localeCompare(b.id);
+}

package/scripts/detect-repo.js

@@ -0,0 +1,118 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function detectRepo(dir = process.cwd()) {
+  const found = new Set();
+  const has = (f) => existsSync(join(dir, f));
+  const pkg = has('package.json') ? safeJson(join(dir, 'package.json')) : null;
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.next || deps.react) { found.add('nextjs'); found.add('design'); }
+  }
+  if (has('pubspec.yaml')) { found.add('flutter'); found.add('design'); }
+  if (has('requirements.txt') || has('pyproject.toml')) found.add('fastapi');
+  if (has('go.mod')) found.add('go');
+  if (has('prisma') || has('migrations') || readdirSafe(dir).some((f) => f.endsWith('.sql'))) found.add('postgresdb');
+  if (has('Dockerfile') || has('compose.yaml') || has('.github')) found.add('deployment');
+  return [...found];
+}
+
+export function detectRepoProfile(dir = process.cwd()) {
+  const has = (f) => existsSync(join(dir, f));
+  const pkg = has('package.json') ? safeJson(join(dir, 'package.json')) : null;
+  const pyproject = has('pyproject.toml') ? readSafe(join(dir, 'pyproject.toml')) : '';
+  const requirements = has('requirements.txt') ? readSafe(join(dir, 'requirements.txt')) : '';
+  const deps = pkg ? { ...pkg.dependencies, ...pkg.devDependencies } : {};
+  const scripts = pickScripts(pkg?.scripts || {});
+  const packageManagers = detectPackageManagers(dir);
+  const testRunners = [];
+  const signals = [];
+
+  if (deps.vitest || /(^|\s)vitest(\s|$)/.test(scripts.test || '')) testRunners.push('vitest');
+  if (deps.jest || /(^|\s)jest(\s|$)/.test(scripts.test || '')) testRunners.push('jest');
+  if (deps['@playwright/test'] || deps.playwright || /playwright/.test(scripts.test || '')) testRunners.push('playwright');
+  if (/pytest/i.test(pyproject) || /pytest/i.test(requirements)) testRunners.push('pytest');
+  if (has('go.mod')) testRunners.push('go test');
+  if (has('pubspec.yaml')) testRunners.push('flutter test');
+
+  const monorepo = Boolean(
+    pkg?.workspaces ||
+    has('pnpm-workspace.yaml') ||
+    has('turbo.json') ||
+    has('nx.json') ||
+    has('lerna.json')
+  );
+  if (pkg?.workspaces) signals.push('package.json#workspaces');
+  for (const f of ['pnpm-workspace.yaml', 'turbo.json', 'nx.json', 'lerna.json']) {
+    if (has(f)) signals.push(f);
+  }
+
+  return {
+    stacks: detectRepo(dir),
+    packageManagers,
+    scripts,
+    testRunners: unique(testRunners),
+    monorepo,
+    signals,
+    commands: recommendedCommands({ scripts, packageManagers, testRunners, has }),
+    strictTdd: testRunners.length > 0,
+  };
+}
+
+function safeJson(p) {
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return {}; }
+}
+
+function readSafe(p) {
+  try { return readFileSync(p, 'utf8'); } catch { return ''; }
+}
+
+function readdirSafe(d) {
+  try { return readdirSync(d); } catch { return []; }
+}
+
+function pickScripts(scripts) {
+  const out = {};
+  for (const k of ['test', 'lint', 'typecheck', 'build']) {
+    if (scripts[k]) out[k] = scripts[k];
+  }
+  return out;
+}
+
+function detectPackageManagers(dir) {
+  const managers = [];
+  if (existsSync(join(dir, 'pnpm-lock.yaml'))) managers.push('pnpm');
+  if (existsSync(join(dir, 'yarn.lock'))) managers.push('yarn');
+  if (existsSync(join(dir, 'bun.lockb')) || existsSync(join(dir, 'bun.lock'))) managers.push('bun');
+  if (existsSync(join(dir, 'package-lock.json'))) managers.push('npm');
+  if (!managers.length && existsSync(join(dir, 'package.json'))) managers.push('npm');
+  return managers;
+}
+
+function recommendedCommands({ scripts, packageManagers, testRunners, has }) {
+  const pm = packageManagers[0] || 'npm';
+  const run = (script) => pm === 'npm' ? `npm run ${script}` : `${pm} run ${script}`;
+  const nodeVerify = ['lint', 'typecheck', 'test', 'build'].filter((s) => scripts[s]).map(run);
+  const apply = [];
+  const verify = [...nodeVerify];
+
+  if (scripts.test) apply.push(run('test'));
+  if (testRunners.includes('pytest')) {
+    apply.push('pytest');
+    if (!verify.includes('pytest')) verify.push('pytest');
+  }
+  if (testRunners.includes('go test')) {
+    apply.push('go test ./...');
+    if (!verify.includes('go test ./...')) verify.push('go test ./...');
+  }
+  if (testRunners.includes('flutter test')) {
+    apply.push('flutter test');
+    if (!verify.includes('flutter test')) verify.push('flutter test');
+  }
+  if (!verify.length && has('go.mod')) verify.push('go test ./...');
+  return { apply: unique(apply), verify: unique(verify) };
+}
+
+function unique(items) {
+  return [...new Set(items)];
+}

package/scripts/doctor.js

@@ -0,0 +1,21 @@
+import { existsSync } from 'node:fs';
+import { targetPaths } from '../targets/index.js';
+import { readState } from './lib/state.js';
+import { loadManifest } from './lib/manifest.js';
+
+export function doctor({ target, home }) {
+  const paths = targetPaths(target, home);
+  const state = readState(paths.stateFile);
+  const manifest = loadManifest();
+  const report = {
+    target,
+    installed: Object.keys(state.skills),
+    missing: [],
+    hookWired: existsSync(paths.hookTarget),
+    manifestSkills: manifest.counts.skills,
+  };
+  for (const [id, e] of Object.entries(state.skills)) {
+    for (const f of e.files) if (!existsSync(f)) report.missing.push(`${id}:${f}`);
+  }
+  return report;
+}

package/scripts/eval-lint.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# eval-lint.sh — validate every skills/*/evals/cases.yaml against the eval minimums.
+#
+# Minimums per skill:
+#   >= 5 should_trigger entries
+#   >= 4 should_not_trigger entries
+#   >= 1 capability scenario
+#
+# Uses python3 for real YAML parsing when available. If python3 is missing,
+# falls back to a basic structural grep check and SKIPs the deep validation
+# with a warning (still enforces presence of evals/cases.yaml and the keys).
+#
+# bash 3.2-safe: no mapfile, no unguarded ${arr[@]} under set -u.
+
+# Resolve repo root (parent of scripts/).
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+REPO_ROOT=$(cd "$SCRIPT_DIR/.." && pwd)
+SKILLS_DIR="$REPO_ROOT/skills"
+
+MIN_TRIGGER=5
+MIN_NOT_TRIGGER=4
+MIN_CAPABILITY=1
+
+HAVE_PY=0
+if command -v python3 >/dev/null 2>&1; then
+  HAVE_PY=1
+fi
+
+fail_count=0
+skill_count=0
+warned_skip=0
+
+# Validate one cases.yaml. Echos "PASS"/"FAIL: reason". Returns 0 on pass, 1 on fail.
+validate_py() {
+  cy="$1"
+  CASES_YAML="$cy" MIN_TRIGGER="$MIN_TRIGGER" MIN_NOT_TRIGGER="$MIN_NOT_TRIGGER" \
+  MIN_CAPABILITY="$MIN_CAPABILITY" python3 - <<'PYEOF'
+import os, sys
+try:
+    import yaml
+except Exception as e:
+    sys.stderr.write("NOYAML\n")
+    sys.exit(3)
+
+path = os.environ["CASES_YAML"]
+mt = int(os.environ["MIN_TRIGGER"])
+mn = int(os.environ["MIN_NOT_TRIGGER"])
+mc = int(os.environ["MIN_CAPABILITY"])
+
+try:
+    with open(path) as f:
+        data = yaml.safe_load(f)
+except Exception as e:
+    print("FAIL: YAML parse error: %s" % e)
+    sys.exit(1)
+
+if not isinstance(data, dict):
+    print("FAIL: top-level YAML is not a mapping")
+    sys.exit(1)
+
+def count(key):
+    v = data.get(key)
+    if v is None:
+        return 0
+    if not isinstance(v, list):
+        return -1  # present but wrong type
+    return len(v)
+
+st = count("should_trigger")
+sn = count("should_not_trigger")
+cap = count("capability")
+
+reasons = []
+if st < 0:
+    reasons.append("should_trigger is not a list")
+elif st < mt:
+    reasons.append("should_trigger=%d (<%d)" % (st, mt))
+if sn < 0:
+    reasons.append("should_not_trigger is not a list")
+elif sn < mn:
+    reasons.append("should_not_trigger=%d (<%d)" % (sn, mn))
+if cap < 0:
+    reasons.append("capability is not a list")
+elif cap < mc:
+    reasons.append("capability=%d (<%d)" % (cap, mc))
+
+if reasons:
+    print("FAIL: " + "; ".join(reasons))
+    sys.exit(1)
+
+print("PASS (should_trigger=%d, should_not_trigger=%d, capability=%d)" % (st, sn, cap))
+sys.exit(0)
+PYEOF
+}
+
+# Fallback: basic structural grep check. Counts top-level list items as lines
+# beginning with two-space indent + "- " that follow each section header.
+# This is intentionally conservative; deep validation is SKIPPED.
+validate_grep() {
+  cy="$1"
+  for key in should_trigger should_not_trigger capability; do
+    if ! grep -Eq "^${key}:" "$cy"; then
+      echo "FAIL: missing top-level key '${key}'"
+      return 1
+    fi
+  done
+  echo "SKIP: python3/yaml unavailable — structural keys present, deep validation skipped"
+  return 0
+}
+
+echo "eval-lint: scanning $SKILLS_DIR"
+echo "minimums: should_trigger>=$MIN_TRIGGER should_not_trigger>=$MIN_NOT_TRIGGER capability>=$MIN_CAPABILITY"
+echo
+
+# Iterate skills deterministically; bash 3.2-safe (no mapfile).
+for skill_path in "$SKILLS_DIR"/*; do
+  [ -d "$skill_path" ] || continue
+  [ -f "$skill_path/SKILL.md" ] || continue
+  skill=$(basename "$skill_path")
+  skill_count=$((skill_count + 1))
+
+  evals_dir="$skill_path/evals"
+  cases_yaml="$evals_dir/cases.yaml"
+
+  if [ ! -d "$evals_dir" ]; then
+    printf '%-22s FAIL: missing evals/ directory\n' "$skill"
+    fail_count=$((fail_count + 1))
+    continue
+  fi
+  if [ ! -f "$cases_yaml" ]; then
+    printf '%-22s FAIL: missing evals/cases.yaml\n' "$skill"
+    fail_count=$((fail_count + 1))
+    continue
+  fi
+
+  if [ "$HAVE_PY" -eq 1 ]; then
+    # Capture output and exit status without tripping set -e.
+    set +e
+    result=$(validate_py "$cases_yaml" 2>/tmp/eval-lint.$$.err)
+    rc=$?
+    set -e
+    if [ "$rc" -eq 3 ] || grep -q NOYAML /tmp/eval-lint.$$.err 2>/dev/null; then
+      # python3 present but pyyaml not installed -> fallback.
+      set +e
+      result=$(validate_grep "$cases_yaml")
+      rc=$?
+      set -e
+      warned_skip=1
+    fi
+    rm -f /tmp/eval-lint.$$.err
+  else
+    set +e
+    result=$(validate_grep "$cases_yaml")
+    rc=$?
+    set -e
+    warned_skip=1
+  fi
+
+  printf '%-22s %s\n' "$skill" "$result"
+  if [ "$rc" -ne 0 ]; then
+    fail_count=$((fail_count + 1))
+  fi
+done
+
+echo
+echo "scanned $skill_count skill(s); $fail_count failure(s)"
+if [ "$warned_skip" -eq 1 ]; then
+  echo "WARNING: deep YAML validation was skipped for one or more skills (python3 or PyYAML unavailable)."
+fi
+
+if [ "$fail_count" -gt 0 ]; then
+  echo "RESULT: FAIL"
+  exit 1
+fi
+
+echo "RESULT: PASS"
+exit 0

package/scripts/install-apply.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { rmSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { planInstall } from './install-plan.js';
+import { targetPaths, writeSkill, wireHook } from '../targets/index.js';
+import { readState, writeState } from './lib/state.js';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+export async function applyInstall({ skillIds, target, home }) {
+  const paths = targetPaths(target, home);
+  const plan = planInstall({ skillIds, target, home });
+  const state = readState(paths.stateFile);
+  for (const step of plan) {
+    if (step.kind === 'skill') {
+      const files = await writeSkill(target, step.id, join(ROOT, step.from), step.to);
+      state.skills[step.id] = { files };
+    } else if (step.kind === 'hook') {
+      await wireHook(target, paths, join(ROOT, 'skills', 'suggest', 'SKILL.md'));
+    }
+  }
+  writeState(paths.stateFile, state);
+  return state;
+}
+
+export function listInstalled({ target, home }) {
+  const paths = targetPaths(target, home);
+  return Object.keys(readState(paths.stateFile).skills);
+}
+
+export async function uninstall({ skillIds, target, home, dryRun }) {
+  const paths = targetPaths(target, home);
+  const state = readState(paths.stateFile);
+  const removed = [];
+  for (const id of skillIds) {
+    const entry = state.skills[id];
+    if (!entry) continue;
+    for (const f of entry.files) {
+      removed.push(f);
+      if (!dryRun && existsSync(f)) rmSync(f, { recursive: true, force: true });
+    }
+    if (!dryRun) delete state.skills[id];
+  }
+  if (!dryRun) writeState(paths.stateFile, state);
+  return removed;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const ids = process.argv.slice(2);
+  applyInstall({ skillIds: ids, target: 'claude' }).then(() => console.log('installed', ids.join(', ')));
+}

package/scripts/install-plan.js

@@ -0,0 +1,13 @@
+import { targetPaths } from '../targets/index.js';
+
+export function planInstall({ skillIds, target, home }) {
+  const t = targetPaths(target, home);
+  const plan = [];
+  for (const id of skillIds) {
+    plan.push({ kind: 'skill', id, from: `skills/${id}`, to: t.skillDir(id) });
+  }
+  if (skillIds.includes('suggest')) {
+    plan.push({ kind: 'hook', target, to: t.hookTarget });
+  }
+  return plan;
+}