/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.

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. Record in the lockfile. Create .claude/skills.lock (schema below) if absent, then upsert <name> with the template hash and, when a .claude/skill-profile.md exists, its profileHash (so update can tell when the profile changed, not just the template).
8. Report. State the skill, the hash installed, the registry source used, 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).
3. Print the drifted skills with the reason, e.g. name abc1234 → def5678 (version) or name (guard miss: idempotency). 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>

Delete .claude/commands/<name>.md and its .claude/skills.lock entry. Report.

Lockfile schema (.claude/skills.lock)

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

• 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.
• 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 and it's not in .claude/commands/? Run skill add X first, then invoke. That makes "use /full-review in a repo that lacks it" just work.
• 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 18b9f3e 2026-06-08 -->