/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/prompts/<name>.md. 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. Create .claude/commands/ if absent, strip any pre-existing <!-- skill-templates: … --> lines from the body, then 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, and guards independently of the agent's judgment: "$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.
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) 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 to the user-global ~/.codex/prompts/ (not version-controlled, deprecated upstream) — only when codex is explicitly a target. 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/prompts/<name>.md. If the lock entry has no targets (an older install), fall back to removing whichever of those three exist. 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 21fe7c3 2026-06-14 -->