/skill

The package manager for Claude Code skills — npm/brew for the skill registry at blamechris/skill-templates. Install, list, and update skills on demand, tailored to the current repo by the agent running this command. No central fan-out, no per-repo deploy PRs.

This replaces the old push-based deploy: instead of a CI job pre-customizing every skill into every repo, a repo pulls a skill the moment it needs one and the invoking agent customizes it inline using the repo's own context.

Arguments

• $ARGUMENTS — a subcommand and optional skill name:
  • add <name> — install a skill into this repo (resolve → customize → write → lock).
  • list — show available skills (from the registry index) vs what's installed here.
  • outdated — show installed skills whose template has moved on in the registry.
  • update [name] — re-install stale skills (all outdated, or just <name>).
  • remove <name> — delete an installed skill and its lock entry.
  • With no argument, default to list.

Concepts

• Registry — blamechris/skill-templates. Holds pure generic templates in generic/<name>.md (with {{CUSTOMIZE: …}} markers) and an index registry.json.
• Index — registry.json at the registry root: one entry per skill with its current template git hash and a one-line description. The cheap source of truth for list/outdated. Regenerated by scripts/build-index.sh.
• Installed skill — .claude/commands/<name>.md in this repo: the template with every {{CUSTOMIZE}} marker filled for this repo, ending with a version stamp.
• Version stamp — the last line of an installed skill: <!-- skill-templates: <name> <hash> <date> -->. The <hash> is the registry template commit the install was built from. This is the per-skill version pin.
• Profile — .claude/skill-profile.md in this repo: the repo's identity and per-skill tailoring notes. The agent reads it (plus CLAUDE.md and the code) to fill {{CUSTOMIZE}} markers. If absent, the agent infers from CLAUDE.md + repo layout and notes in its report that a profile would sharpen future installs.
• Lockfile — .claude/skills.lock (JSON): the manifest of what's installed and at which template hash. Lets outdated/update work from repo-local state.
• Targets — the coding agents a skill is compiled for. .claude/commands/<name>.md (the customized install) is the provider-NEUTRAL source; scripts/compile-skill-targets.mjs emits each agent's NATIVE custom-command format: claude → .claude/skills/<name>/SKILL.md, gemini → .gemini/commands/<name>.toml, codex → .codex/skills/<name>/SKILL.md, pi → ~/.pi/agent/skills/<name>/SKILL.md. The first three are repo-tracked; pi is the one user-global target — Pi has no repo-local discovery, so its artifact lands in the user's home dir and is opt-in rather than a safe default. The active list comes from the targets: line in .claude/skill-profile.md (prompt the user if absent; the compiler falls back to claude). This is what makes a skill model-agnostic — author once, run under any model. The neutral arg token is $ARGUMENTS; the compiler maps it per agent (e.g. Gemini {{args}}). The compiler ships in the registry at assets/compile-skill-targets.mjs.

Resolving the registry

Find the registry once, in this order; use the first that works:

1. $SKILL_REGISTRY_DIR if set — a local clone path.
2. ~/Projects/skill-templates if it exists — the conventional local clone (fast, works offline for reads).
3. Otherwise fetch over the network with gh:
   • Index: gh api repos/blamechris/skill-templates/contents/registry.json --jq '.content' | base64 -d
   • Template: gh api repos/blamechris/skill-templates/contents/generic/<name>.md --jq '.content' | base64 -d
   • Hash of a template: gh api 'repos/blamechris/skill-templates/commits?path=generic/<name>.md&per_page=1' --jq '.[0].sha[0:7]'

When using a local clone, refresh it only when online and tolerantly: git -C "$REG" pull --ff-only --quiet 2>/dev/null || true. A failed fetch (offline) or a non-fast-forward leaves the existing clone usable — fall back to its current state and note in the report that hashes may be stale. Record which source you used.

Instructions

skill list

1. Resolve the registry and read registry.json.
2. Read this repo's .claude/skills.lock (treat missing as empty) and list .claude/commands/*.md (treat a missing directory as no skills installed — a bare repo being bootstrapped).
3. Print a table: skill, registry hash, installed hash (from the stamp/lock), and status — installed / outdated / not installed. Group installed first.

skill add <name>

1. Resolve & fetch. Read registry.json; confirm <name> exists (if not, suggest near matches from the index and stop). Fetch generic/<name>.md and capture its current template hash.

2. Gather repo context. Read CLAUDE.md, .claude/skill-profile.md (if present), and enough of the repo (layout, test/build commands, labels, conventions) to fill the template's {{CUSTOMIZE: …}} markers. The marker text describes what each spot needs.

3. Customize inline. Produce the final skill markdown by following the registry's customization rules exactly:

   • Replace every {{CUSTOMIZE: …}} marker with content derived from the repo context. The marker text says what kind of content is needed.
   • If the repo context has nothing relevant for a marker, remove the marker line entirely — never leave a blank or placeholder marker.
   • Preserve all non-customizable text exactly — do not rephrase, reorder, or "improve" anything that isn't a marker. Preserve all code blocks and formatting.
   • Remove the entire trailing ## Customization Points section (it's meta-docs for template maintainers, not part of a deployed skill).
   • Never invent specifics. If a marker asks for examples the repo context does not provide (file:line citations, label names, agent rosters, commands), use placeholder shapes (path/to/file:<line>, scope) rather than fabricating.
   • No attribution anywhere — no "Generated with", no "Co-Authored-By", no AI mentions (this is a hard registry rule).

4. Self-validate before writing (the agent IS the validator here — these cover the registry's validate_output checks, including its skeleton-preservation pass):

   • No residual markers: no {{CUSTOMIZE remains (outside backticked mentions).
   • No attribution footer: none of the last ~15 lines start with "Generated with Claude" / "Co-Authored-By: Claude".
   • Headings preserved (exact): every real markdown heading from the template (minus the removed ## Customization Points) appears verbatim in the output.
   • Body preserved: non-heading, non-marker template lines survive in the output — only the spots where a {{CUSTOMIZE}} marker was filled or removed may differ. Do not silently drop or reword the template's prose, code blocks, or examples.
   • Length sane: output is roughly 50–200% of the template length (catches truncation or runaway expansion).
   • No forged stamp: the customized body contains no <!-- skill-templates: … --> line of its own. Strip any before step 5 appends the single authoritative stamp, so outdated can't be fooled by a planted version.
   • Guards intact: if this skill has a guards array in registry.json, every guard must still be satisfied — for each guard, at least one of its anyOf regexes matches the customized output. A guard miss means customization stripped a load-bearing section; restore it. (These are the content checks ported from sync.sh.)
   • If any check fails, fix and re-check before writing. Never write defective output.

5. Write + stamp. This writes into the repo's shared working copy, which another session may have moved to its own branch since this one started — so re-check first: git branch --show-current. If it is not the branch you started on, STOP and tell the user rather than writing; a skill install landing on someone else's branch is how it gets swept into their commit. Then create .claude/commands/ if absent, strip any pre-existing <!-- skill-templates: … --> lines from the body, and write to .claude/commands/<name>.md ending with exactly: <!-- skill-templates: <name> <hash> <date> --> (today's date, YYYY-MM-DD).

6. Lint (deterministic gate). Run the registry's mechanical linter on the file just written — it re-checks markers, attribution, the stamp, guards, and the posture pin independently of the agent's judgment. From a local clone (the preferred path): "$REG/scripts/skill-lint.sh" <name> .claude/commands/<name>.md (where $REG is the resolved registry clone). If it exits non-zero, fix the reported issues and re-lint before recording the lockfile — do not lock a skill that fails lint. Consumers can run the same linter as a pre-commit hook or in CI.

   On the network-only path (source 3 — no clone on disk, so $REG is unset and that command expands to /scripts/skill-lint.sh: exit 127, gate not run at all), fetch the linter the way step 7 fetches the compiler, and pass registry.json explicitly as the third argument — the index from step 1 has to exist as a file here, not just in context:

   set -o pipefail
   lintdir="$(mktemp -d)"
   gh api repos/blamechris/skill-templates/contents/scripts/skill-lint.sh \
     --jq '.content' | base64 -d > "$lintdir/skill-lint.sh" || exit 1
   gh api repos/blamechris/skill-templates/contents/registry.json \
     --jq '.content' | base64 -d > "$lintdir/registry.json" || exit 1
   [ -s "$lintdir/skill-lint.sh" ] && [ -s "$lintdir/registry.json" ] || {
     echo "lint gate unavailable: a fetch produced an empty file" >&2; exit 1; }
   bash "$lintdir/skill-lint.sh" <name> .claude/commands/<name>.md "$lintdir/registry.json"
   

   Three details are load-bearing:

   • The fetch guards — gh failing (offline, 404, rate limit) leaves a 0-byte file behind, and bash on an empty file exits 0 printing nothing, which this document's own outcome table below reads as "clean, all four checks passed". Unguarded, the network path's failure mode is a silent green gate — worse than the exit 127 this section exists to fix, because 127 is at least loud. Source 3 is reached exactly when there is no clone to fall back on, and "Resolving the registry" above explicitly contemplates being offline.
   • bash <path> — a redirected fetch lands non-executable (the exact mode is umask-dependent; what matters is that no execute bit is set), so running it directly exits 126 (permission denied), not 127. Same skipped gate, different code.
   • The third argument — with it omitted the linter defaults its registry to <the script's own dir>/../registry.json, which for a copy under a temp dir is not this registry. Either that path is absent, and the run exits 2 printing ERROR: registry not found … on stderr with an empty stdout — the findings it had already collected are discarded unprinted, so a caller watching the output sees exactly what a pass looks like — or some unrelated registry.json sits there and gets loaded instead, in which case a skill it happens to name with no guards of its own lints ✓ <name>: clean (0 guard(s) ok) at exit 0, with this registry's guards never applied.

   The linter has three outcomes. Key on the exit code, not on the output markers — ERROR: is printed for an unknown skill and then followed by findings at exit 1, and a usage error exits 2 printing no marker at all. Only ~ is exclusive to exit 2.

   • exit 0 (✓) — clean, every check passed.
   • exit 1 (✗) — real findings. Fix and re-lint; never lock. This includes a file that is stamped but absent from the index: a stamp is proof of a registry install, so an index that has never heard of the skill means a stale clone, a renamed or retired skill, a typo'd <name>, or the wrong registry.json — and its guards went unapplied. The reported findings name which, and the stamp checks are applied on this path too.
   • exit 2 — could not be fully verified. Six causes, and only one is benign: an unstamped skill absent from the index (the ~ line — a repo-only skill, with genuinely nothing to verify), plus missing registry file, missing python3, unreadable skill file, an explicitly passed profile that cannot be read, and usage error. The last five are environment breakage.

   For skill add, exit 2 is always a failure: add stops before writing if the name is absent from the index, so by lint time the skill is in the index by construction — exit 2 there means a stale index, a wrong name, or a broken environment.

   For a pre-commit hook or CI linting a whole .claude/commands/ directory, exit 2 is far narrower than it was: a stale index — which used to turn a real ✗ guard miss into a clean-looking ~ — is now reported as a finding at exit 1. What remains at 2 is a genuinely repo-only file or environment breakage (missing/wrong-path registry, no python3, unreadable file), and the linter cannot tell a hook which of those it hit. So keep the version-stamp test: a stamped file can no longer legitimately exit 2, because provenance means the index should know it. Tolerating 2 unconditionally re-opens the hole this change closes — for the 270 stamped files in the current fleet, a mistyped registry path would go from caught to silently green.

   scripts/skill-lint.sh "$name" "$file" ; rc=$?
   if [ "$rc" -eq 1 ]; then exit 1; fi   # includes a stamped file the index does not know
   

   Earlier revisions of this step told the hook to re-test the file itself with grep -q '^<!-- skill-templates: ' and fail on a stamped exit 2. That existed only because exit 2 covered both conditions and the caller had to re-derive which one it had hit. Do not reintroduce it: it re-implements, less accurately, a check the linter already runs — the grep cannot see a stamp behind leading whitespace, and cannot distinguish a well-formed stamp from a mangled one.

7. Compile to native targets. Ensure the compiler exists in this repo (create scripts/ if absent). If scripts/compile-skill-targets.mjs is missing — or you're running update, so it stays current with the registry — (re)fetch it: from a local clone, cp "$REG/assets/compile-skill-targets.mjs" scripts/; on the network-only path (no local clone), fetch it like the templates — gh api repos/blamechris/skill-templates/contents/assets/compile-skill-targets.mjs --jq '.content' | base64 -d > scripts/compile-skill-targets.mjs. Write it to scripts/ and track it in VCS so it travels with the repo. Read the targets: line from .claude/skill-profile.md; if there is none, ask the user which agents to compile for (claude / gemini / codex / pi) and offer to record the choice in the profile (the compiler falls back to claude if unset). Then run node scripts/compile-skill-targets.mjs --name <name> (it reads the profile targets), or --targets <list> to override. It writes the native artifact per target and exits non-zero on any emit failure — treat that as a hard gate: fix and re-run before locking. Codex emits a repo-tracked skill folder under .codex/skills/ so it can be reviewed, copied into ~/.codex/skills, or used by runners that support repo-local Codex skills. pi writes outside the repo (~/.pi/agent/skills/), so only add it when the user actually drives this repo with Pi — never volunteer it into a committed targets: line on their behalf. The compiler prints a hint if it sees ~/.pi on the machine but pi is unselected; that hint is advisory and never adds the target itself. Keep the list of targets you compiled with for the next step.

8. Record in the lockfile. Only after a successful compile, create .claude/skills.lock (schema below) if absent and upsert <name> atomically with: the template hash; the profileHash when a .claude/skill-profile.md exists (so update can tell when the profile changed, not just the template); and the targets you just compiled with (so remove cleans exactly the right native artifacts and outdated can detect target drift). Writing the entry only after compile succeeds means a failed compile never leaves a half-written or targets-less entry.

9. Report. State the skill, the hash installed, the registry source used, the targets compiled (with output paths), and any markers dropped for lack of repo context.

skill outdated

1. Resolve the registry and read registry.json.
2. For each entry in .claude/skills.lock (or each stamped .claude/commands/*.md), flag it stale if any of:
   • version drift — installed hash ≠ the registry's current hash;
   • profile drift — the lockfile's profileHash ≠ the current .claude/skill-profile.md hash (the skill was tailored against an older profile);
   • corruption drift — the installed file fails a registry guard (some guard's anyOf regexes no longer match — a load-bearing section was lost).
   • target drift — only when the lock entry has a targets array (a pre-targets install with no such field is treated as "unknown" — fall back to disk inspection, never flagged just for the field's absence): the profile's targets: list has an agent not in the lock entry's targets (added to the profile but never compiled), or a recorded target's native artifact is missing on disk — excluding targets the compiler intentionally skips (e.g. Gemini for a body containing {{…}} / !{…} / @{…}, which is never emitted and so isn't real drift). A plain recompile fixes genuine target drift — no registry fetch needed.
3. Print the drifted skills with the reason, e.g. name abc1234 → def5678 (version) or name (guard miss: idempotency) or name (target drift: gemini not compiled). If none, say so. (This is the consumer-side port of the registry's sync.sh drift check — version stamp and content guards.)

skill update [name]

1. Run outdated. If <name> is given, narrow to it.
2. For each stale skill, re-run add (which re-fetches, re-customizes against current repo context, and re-stamps). Skip skills already current.
3. Report what was updated old → new and what was already current.

skill remove <name>

Read the skill's targets from its .claude/skills.lock entry, then delete .claude/commands/<name>.md, its lock entry, and exactly the native artifacts for those targets: claude → .claude/skills/<name>/ (dir), gemini → .gemini/commands/<name>.toml, codex → .codex/skills/<name>/ (dir), pi → ~/.pi/agent/skills/<name>/ (dir, outside the repo — remove it only when pi is in the lock entry's targets, and say so in the report since the user may not expect a repo command to touch their home dir). If the lock entry has no targets (an older install), fall back to removing whichever of the three repo-local artifacts exist — never probe ~/.pi on a guess, because an unrelated Pi skill of the same name could live there. Report what was removed.

Lockfile schema (.claude/skills.lock)

{
  "registry": "blamechris/skill-templates",
  "skills": {
    "full-review": { "hash": "cc062bc", "installed": "2026-06-04", "profileHash": "3f1a9c2", "targets": ["claude", "gemini"] },
    "check-pr":    { "hash": "a10ef75", "installed": "2026-06-04", "targets": ["claude"] }
  }
}

• hash — the registry template commit this install was built from (matches the version stamp). outdated diffs this against registry.json.
• installed — date the install/update ran (YYYY-MM-DD).
• profileHash (optional) — short hash of .claude/skill-profile.md at install time. Present only when a profile existed. outdated flags profile drift when it no longer matches the current profile, so a changed profile triggers a re-tailor on update.
• targets (optional) — the agents this skill was compiled for at install time (e.g. ["claude", "gemini"]). Written by the add compile step; remove uses it to delete exactly the right native artifacts, and outdated uses it to detect target drift. Absent on pre-targets installs — treat a missing targets as "unknown" and fall back to disk inspection.
• The lockfile is the authoritative manifest; the per-file stamp is a convenient inline mirror. Keep them in agreement.

Notes

• The agent is the customizer. No Haiku/API key — the agent running /skill tailors the template with full repo context, which is richer than a context-blind batch job. The self-validation step replaces the registry's automated validate_output.
• Auto-install on miss. A repo or global CLAUDE.md rule should say: asked to run /X? Check the neutral source .claude/commands/X.md. Missing → not installed → skill add X. Present but the native artifact (.claude/skills/X/SKILL.md) is missing → just not compiled → recompile with node scripts/compile-skill-targets.mjs --name X (no registry fetch). Then invoke. That makes "use /full-review in a repo that lacks it" just work without re-fetching when a recompile suffices.
• Compile is deterministic. The generic→native transform lives in scripts/compile-skill-targets.mjs, not in agent judgment, so the native artifacts are reproducible. Edited a skill's generic source (.claude/commands/<name>.md) by hand? Recompile with node scripts/compile-skill-targets.mjs --name <name> (--dry-run previews).
• Idempotent. Re-running add for a current skill is a no-op re-render; re-running for a moved template updates it. Safe to run anytime.
• Self-contained on first use. /skill needs no customization to work — it ships with sane registry defaults so it can bootstrap a repo that has nothing else installed.

<!-- skill-templates: skill af9c1e4 2026-08-03 -->