@ssheleg/make-skill 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # Changelog
 
+## v0.9.0 — 2026-08-03
+
+The canon knew the Claude Code capability set and used none of it. This release
+uses it — and turns the missing half into a rule: **every host capability is an
+accelerator with a written fallback**, because hooks, subagents and `/commands`
+exist only inside Claude Code, which is a minority of where skills run.
+
+### Added
+- **`references/host-capabilities.md`** — hooks (events, handler types, matchers,
+  `if` rules, exit-code semantics, structured output, plugin-scoped MCP matchers),
+  subagents, commands, scripts, MCP and sibling-skill dependencies: what each
+  buys, what it costs in always-on tokens, and when it earns its place. Verified
+  against the hooks reference and against a working plugin, not from memory.
+- **The degradation contract**, in `SKILL.md` and enforced by the validator.
+  Three axes, each written in the body where the agent will read it: not Claude
+  Code (no hooks/subagents/commands — name the inline procedure), recommended
+  plugin absent (say what is degraded, continue), tool or MCP server absent
+  (state it once, fall back, never retry in a loop). *A fallback you know but did
+  not write is not a fallback.*
+- **`scripts/audit_skill.py`** — a stdlib auditor for ANY skill directory: name
+  charset/length/reserved words/XML tags/directory match, description limits and
+  third person, frontmatter keys, body budgets, bundled-file reachability and
+  nesting, tables of contents past 100 lines, link escapes, Windows paths,
+  time-branching prose, bare directory pointers. `--house` adds the ssheleg
+  rules. It finds all nine planted defects in the evaluation fixture and passes
+  clean on this skill; CI asserts both.
+- **A `PostToolUse` hook** that audits a `SKILL.md` the moment it is written, and
+  is otherwise invisible: it exits 0 with no output for any other path, for a
+  missing `python3`, for a missing script. It advises via `systemMessage` and
+  never blocks — `PostToolUse` fires after the write, so a veto costs a turn and
+  buys nothing.
+- **`commands/skill-audit.md`** (deliberately not named after the skill) and
+  **`agents/skill-auditor.md`** — a subagent for auditing a repo full of skills
+  without crowding the main thread, including the coexistence check that is
+  invisible per-skill.
+- **Six skeletons in `assets/`**, now *inside* the skill directory so they travel
+  on every channel: SKILL, plugin manifest, marketplace manifest, and new hooks,
+  agent and command templates, each carrying its degradation clause.
+- **`SKILL-CARD.md`** — the enterprise registry entry plus an honest pass over
+  the risk table, including the hook that runs automatically. **`test/evals/RESULTS.md`**
+  states plainly that the suite has never been executed against a model.
+- Frontmatter `compatibility` (what this skill needs and where it does not work)
+  and `metadata.version`, which is the only version an agent outside Claude Code
+  can see — now the fifth point of the version-sync rule.
+
+### Fixed
+- **The skeletons reached no agent.** `templates/` sat at the repo root, outside
+  the plugin directory and outside the skill directory, so neither the Claude
+  Code plugin nor the skills CLI ever shipped them. They are `assets/` now, and
+  the validator fails if a root `templates/` reappears.
+- The auditor's own first run flagged a false positive on this skill's
+  anti-pattern gotcha ("Before August, use the old API" — quoted as an example).
+  Quoted and backticked spans are now excluded: a linter that flags the document
+  warning about the thing it detects earns the habit of being ignored.
+- New validator rules, each with a negative self-test: hook commands must resolve
+  through a quoted `${CLAUDE_PLUGIN_ROOT}` and carry a timeout, hook scripts must
+  exist with a shebang and the executable bit, plugin agents must not carry
+  `hooks`/`mcpServers`/`permissionMode`, shipped scripts must compile, and the
+  degradation section must be present.
+
+## v0.8.1 — 2026-08-03
+
+A file-by-file re-read of everything 0.8.0 touched, and of everything it didn't.
+Fourteen findings, all fixed. The two that would have misled a reader:
+
+### Fixed
+- **The token estimate was asserted, not measured.** The validator's comment
+  claimed dense markdown runs "closer to 3.7 chars/token, so this under-reports";
+  nothing had ever been counted. Tokenizing the bundle gives **3.78–4.47**
+  chars/token (3.9 for `SKILL.md`), so the divisor is now 3.9, measured — and
+  the recalibration immediately failed the body it was checking, which is what a
+  calibrated rule is for. The audit checklist moved to a new
+  **`references/retrofit.md`**, bringing the body to ~4.6k tokens with headroom.
+- **`claude plugin details` and a real tokenizer disagree by ~40%** — the CLI
+  reported ~7.2k on-invoke for a `SKILL.md` that tokenizes at ~5.0k, because its
+  estimator assumes ~2.8 chars/token. Measured across six installed skills and
+  recorded as a gotcha: budget against a tokenizer, expect the CLI to look
+  alarming, and never gut a body that is genuinely inside the budget.
+- **`SECURITY.md` described paths the installers do not write.** It claimed
+  `bin/make-skill.js` and `install.sh` copy into `~/.claude/commands/`; that
+  command file was deleted in 0.6.x and CI asserts its absence on every run. The
+  threat model now matches the code, and states what `test/evals/fixtures/` is —
+  including that the malicious sample is inert data, never installed.
+- **The trigger split could not measure what it claimed.** `train: q01-q12` /
+  `validation: q13-q20` put all ten positives in train and left validation with
+  nothing but negatives, so the held-out half could only detect false-firing.
+  Split is now explicit ids with both classes on both sides, and the validator
+  rejects a half that holds only one class.
+- **`displayName` was required by the canon and absent from the skeletons.**
+  Both manifest templates now seed it, and the validator enforces it in the
+  templates, in `plugin.json`, and in the marketplace entry — where it belongs
+  (the marketplace root takes neither `displayName` nor `homepage`).
+- **`/make-skill` is only half the truth.** As a plugin the command is
+  `/make-skill:make-skill`; the bare form is what a skills-directory install
+  gets. README and canon now state both, and the canon says to write both rather
+  than promise one.
+- `distribution.md`'s table of contents listed a "shadow rule" section that did
+  not exist as a heading — the exact failure a table of contents prevents. It is
+  a real section now.
+- Counts that had drifted: CONTRIBUTING said CI runs "four negative self-tests"
+  (six groups), the issue-template contact link said "the other four skills"
+  (five), the retrofit fixture header claimed eight planted defects (nine, now
+  scored one per line).
+- Dead `EVAL_DIR` variable removed; `test/evals/` added to the Cursor rule's
+  layout tree and to the templates README, both of which still described a repo
+  without it; the PR template now asks for the two `--strict` runs and for an
+  eval re-run when the description changes.
+- Three more negative self-tests (split classes, `displayName` ×2), keeping the
+  rule that no validator rule ships without one.
+
 ## v0.8.0 — 2026-08-03
 
 Read Anthropic's four Agent Skills pages end to end (overview, authoring best
@@ -63,9 +173,10 @@ six new validator rules, and one self-violation fixed.
 - **This skill was over its own token budget.** `SKILL.md` was ~5.2k estimated
   tokens against a stated `< 5000` — a rule the repo enforced on everyone but
   itself, because only the 500-line half was ever checked. The body budget is
-  now measured (chars/4, frontmatter excluded as level-1 metadata) and the body
-  was cut to ~4.6k by moving the repo layout, the two Claude Code gates, the
-  validator spec and the release checklist into `references/distribution.md`.
+  now measured (frontmatter excluded as level-1 metadata) and the body was cut
+  by moving the repo layout, the two Claude Code gates, the validator spec and
+  the release checklist into `references/distribution.md`. (The divisor used
+  here was a guess; v0.8.1 measured it and cut further.)
 - **Reference files longer than 100 lines now open with a `## Contents` list.**
   Agents preview long files with `head`; without a table of contents they act on
   the first hundred lines and never learn the rest exists. All eight references

package/README.md

@@ -31,11 +31,21 @@ make a skill that turns our incident runbooks into a triage workflow
 …or point it at something that already exists:
 
 ```
-/make-skill audit ./skills/my-skill against the spec
+/make-skill:make-skill audit ./skills/my-skill against the spec
 ```
 
-Inside a skill repo, `/make-skill` with no argument detects the situation and runs
-the audit rather than asking you what you meant.
+…or run just the mechanical half against any skill directory, no agent turn
+required:
+
+```bash
+python3 ~/.claude/plugins/*/make-skill/*/skills/make-skill/scripts/audit_skill.py ./my-skill --house
+```
+
+With no argument the skill detects the situation — a `SKILL.md` or
+`.claude-plugin/` in the current directory means it runs the audit rather than
+asking you what you meant. The command is `/make-skill:make-skill` when installed as a plugin and
+`/make-skill` when it sits in a skills directory; both reach the same skill, and
+asking in plain language works either way.
 
 ## What it does
 
@@ -74,6 +84,17 @@ both manifests, in CI as its own job. That check is what caught this repo's own
 `marketplace.json` shipping `homepage` and `repository` at a level where Claude
 Code ignores them.
 
+**The Claude Code power set — with a fallback for everywhere else.** The skill
+ships what it teaches: a `PostToolUse` **hook** that audits a `SKILL.md` the
+moment you save one (and exits silently for every other write, in every other
+project), a **subagent** for auditing a repo full of skills without crowding the
+main thread, a `/skill-audit` **command**, and a stdlib **script** that does the
+mechanical half of an audit deterministically. Hooks, subagents and commands
+exist only inside Claude Code — so the canon makes the fallback a rule: **every
+host capability is an accelerator with a written fallback**, for three named
+cases (not Claude Code, recommended plugin absent, tool or MCP server absent).
+A fallback you know but did not write is not a fallback.
+
 **Evaluations, not vibes.** The canon requires every skill to carry at least
 three behavioral scenarios and a trigger set whose negatives are *near-misses* —
 queries that share the keywords and need something else. make-skill ships its
@@ -122,15 +143,19 @@ agent opens only when the situation calls for them:
 | `authoring.md` | the craft — naming, third-person descriptions, degrees of freedom, workflows and feedback loops, script rules, evaluation-driven development |
 | `surfaces.md` | Claude Code vs the Claude API vs claude.ai — the Skills API (upload, versions, 8 per request), and the no-network / no-package-install limits that break scripts moved between surfaces |
 | `enterprise.md` | installing a skill you didn't write, and running a fleet — risk tiers, the review checklist, the five approval gates, lifecycle, recall limits, rollback |
+| `retrofit.md` | the audit procedure — the 14-item checklist, what counts as evidence for a PASS, and the short form for a personal skill |
+| `host-capabilities.md` | hooks, subagents, commands, scripts and MCP dependencies — what each buys, what it costs in always-on tokens, hook events and exit-code semantics, and the degradation clauses that keep a skill working where none of them exist |
 | `claude-code-plugin.md` | the [Claude Code layer](https://code.claude.com/docs/en/plugins-reference) — `plugin.json` / `marketplace.json` schemas, plugin sources, component locations, host-only front-matter, path variables, cache and symlink rules, the `claude plugin` CLI |
 | `distribution.md` | the repo layout, every install channel, exact CLI flags, npm publishing traps, the release checklist |
 | `mcp.md` | [MCP](https://modelcontextprotocol.io) — skill vs server, primitives and methods, transports, consent and untrusted-output rules |
 | `a2a.md` | [A2A](https://a2a-protocol.org) — Agent Cards, task lifecycle, method mapping, v0.x→1.0 wire drift |
 
-Plus three skeletons in `templates/`: `SKILL.template.md` with the spec limits
-written into it, and `plugin.template.json` / `marketplace.template.json`, which
-carry only fields Claude Code recognizes so a seeded repo passes
-`claude plugin validate --strict` on day one.
+Plus six skeletons in `skills/make-skill/assets/` — inside the skill directory,
+so they reach every channel: `SKILL.template.md` with both rulebooks' limits
+written into it, `plugin.template.json` / `marketplace.template.json` carrying
+only fields Claude Code recognizes (a seeded repo passes `claude plugin validate
+--strict` on day one), and `hooks.template.json` / `agent.template.md` /
+`command.template.md`, each with its degradation clause already in place.
 
 ## Install
 
@@ -197,9 +222,14 @@ copy on every global update, even when Claude Code was never named.
 
 ### Requirements
 
-Node ≥ 16 for the `npx` installer; Python 3 only if you run the validator;
-`bash` for `install.sh` (Windows users: use `npx`, the plugin, or the skills CLI).
-The skill itself is plain Markdown and needs nothing.
+Node ≥ 16 for the `npx` installer; **Python 3 for the bundled auditor and the
+validator** (without it the skill falls back to the same checks by hand, and
+says so); `bash` for `install.sh` and the hook (Windows users: use `npx`, the
+plugin, or the skills CLI). The canon itself is plain Markdown and needs nothing.
+
+What runs on its own: one `PostToolUse` hook, which exits silently unless the
+file you just wrote is a `SKILL.md`. It is 30 lines and is described in
+[SECURITY.md](SECURITY.md) and [SKILL-CARD.md](SKILL-CARD.md).
 
 ## Repo layout
 
@@ -207,16 +237,20 @@ The skill itself is plain Markdown and needs nothing.
 .claude-plugin/marketplace.json
 plugins/make-skill/
 ├── .claude-plugin/plugin.json
-└── skills/make-skill/                # the skill IS /make-skill — no command file
-    ├── SKILL.md                      # the canon, < 500 lines by rule
-    └── references/*.md               # loaded on demand
+├── skills/make-skill/                # everything here travels to every agent
+│   ├── SKILL.md                      # the canon, < 500 lines and < 5000 tokens by rule
+│   ├── references/*.md               # loaded on demand
+│   ├── scripts/audit_skill.py        # audits any skill dir, stdlib only
+│   └── assets/*.template.*           # six skeletons: skill, manifests, hooks, agent, command
+├── hooks/                            # Claude Code only — PostToolUse SKILL.md audit
+├── agents/skill-auditor.md           # Claude Code only
+└── commands/skill-audit.md           # Claude Code only, never named after a skill
 cursor/rules/make-skill.mdc           # self-contained Cursor rule
-templates/                            # SKILL.template.md + the two manifest skeletons
 bin/make-skill.js + package.json      # zero-dep npx installer
 test/validate.py                      # structural validator
 test/evals/                           # trigger set + behavioral scenarios (data)
 .github/workflows/{validate,release}.yml
-install.sh  README.md  CHANGELOG.md  CONTRIBUTING.md  SECURITY.md  LICENSE
+install.sh  README.md  CHANGELOG.md  CONTRIBUTING.md  SECURITY.md  SKILL-CARD.md  LICENSE
 docs/superpowers/{specs,plans}/       # historical design records
 ```
 

package/SECURITY.md

@@ -13,15 +13,31 @@ unless you'd prefer otherwise.
 
 ## What this project touches
 
-`make-skill` ships Markdown plus two small installers. Knowing exactly what runs
-where is most of the threat model:
-
-- **`bin/make-skill.js`** (run via `npx`) and **`install.sh`** copy files into
-  `~/.claude/skills/make-skill` and `~/.claude/commands/`. They create and
-  overwrite only those paths, never elsewhere in `$HOME`, and overwrite only with
-  `--force`. Both are zero-dependency: no network calls, no postinstall script.
+`make-skill` ships Markdown, two small installers, one auditor script and one
+hook. Knowing exactly what runs where is most of the threat model — and the hook
+is the only thing that runs without you asking:
+
+- **`plugins/make-skill/hooks/skill-md-audit.sh`** runs on every `Write`,
+  `Edit` and `MultiEdit` **in every project** once the plugin is enabled. It
+  reads the hook's stdin JSON and **exits 0 immediately, printing nothing,
+  unless the written path ends in `SKILL.md`** — so in a project that does not
+  author skills it is a no-op you never see. When it is a `SKILL.md`, it runs
+  the bundled auditor on that directory and returns the report as advice
+  (`systemMessage`). It never blocks, never writes a file, never makes a network
+  call, and needs no `jq`. Thirty lines; read them before enabling the plugin.
+- **`skills/make-skill/scripts/audit_skill.py`** reads a skill directory and
+  prints a report. Standard library only. It writes nothing and is run by you,
+  the `/skill-audit` command, the subagent, or the hook above.
+- **`bin/make-skill.js`** (run via `npx`) and **`install.sh`** copy the skill
+  directory into `~/.claude/skills/make-skill` and nothing else — no command file,
+  no other path in `$HOME` — and overwrite only with `--force`. Both are
+  zero-dependency: no network calls, no postinstall script. CI asserts the
+  absence of `~/.claude/commands/make-skill.md` on every run.
 - **`test/validate.py`** reads repository files and exits with a status. It writes
-  nothing.
+  nothing. `test/evals/` is inert data — text a human feeds to an agent — and
+  `test/evals/fixtures/untrusted-skill.md` is a deliberately malicious *sample*
+  used to score a review; it is never installed or executed, and its endpoints
+  are `example.com` placeholders.
 - The Claude Code plugin and the `skills` CLI channels are handled by those tools,
   not by code in this repo.
 

package/cursor/rules/make-skill.mdc

@@ -77,6 +77,7 @@ cursor/rules/*.mdc                         # self-contained, NO relative links
 templates/*.md                             # skeletons — NEVER name one SKILL.md
 bin/<name>.js + package.json               # zero-dep npx installer
 test/validate.py                           # stdlib-only consistency validator
+test/evals/                                # triggers.json + scenarios.json (data, run by a human)
 .github/workflows/validate.yml (+ release.yml, off by default)
 install.sh, README.md (English-first), CHANGELOG.md, LICENSE (MIT)
 CONTRIBUTING.md + SECURITY.md              # required once the repo is public
@@ -113,6 +114,30 @@ checker, not a house opinion:
   `${CLAUDE_PLUGIN_DATA}` — both Claude-Code-only, so keep relative paths as the
   portable contract.
 
+## Host capabilities and the degradation contract
+
+Hooks, subagents, `/commands`, `${CLAUDE_PLUGIN_ROOT}` and MCP servers exist only
+inside Claude Code — which is a minority of where skills run. **Each is an
+accelerator with a WRITTEN fallback; the skill still finishes its job without
+it.** Put all three cases in the body, in the words the agent reads when it hits
+them:
+
+- **Not Claude Code** (Cursor, Codex, skills CLI, API): no hooks, no subagents,
+  no `/command`. Name the inline procedure. Bundled `scripts/` still travel —
+  they live inside the skill dir — so give the path per channel.
+- **Recommended plugin/skill absent**: say once what is degraded, then continue
+  on the manual path. A stage that refuses to start because an optional
+  companion is missing is broken, not strict.
+- **Tool, interpreter or MCP server absent**: state it once, fall back to the
+  by-hand procedure, never retry in a loop; interactive auth is a human step.
+
+If you do ship them: `hooks/hooks.json` at the plugin root, commands resolved
+through a quoted `"${CLAUDE_PLUGIN_ROOT}/…"` with a `timeout`; hook scripts exit
+0 silently when the event is not theirs and when the interpreter is missing;
+`PreToolUse` blocks (exit 2 sends stderr to the model), `PostToolUse` advises via
+`systemMessage`; plugin agents may not carry `hooks`, `mcpServers` or
+`permissionMode`; a command is never named after a skill in the same plugin.
+
 ## Hard rules
 
 - **Version sync:** marketplace.json, plugin.json, package.json (if npm), and the
@@ -132,6 +157,10 @@ checker, not a house opinion:
 - **Cursor .mdc:** embed contracts inline (files get copied into foreign projects).
 - **e2e npx from a NON-repo cwd** (inside the repo it resolves the local package →
   false "command not found").
+- **Two token counters, ~40% apart:** `claude plugin details` assumes ~2.8
+  chars/token and shows a far bigger on-invoke cost than a real tokenizer
+  (3.8–4.5 chars/token). Budget the body against a tokenizer; expect the CLI to
+  look alarming for a file that is genuinely inside 5000 tokens.
 - **Installing a skill you did not write is installing software.** Read every
   file, run scripts sandboxed, grep for network calls and credentials, and check
   the instructions for "ignore previous rules", hidden actions, or data routed

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.8.0",
-  "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way — conformance to the Agent Skills open standard AND Anthropic's platform rules (front-matter limits, disclosure budgets, per-surface runtime limits, the Skills API, evals) plus the Claude Code plugin reference (manifest schemas, component layout, claude plugin validate --strict), marketplace repo layout, version sync, validator + CI, multi-channel distribution (plugin, vercel skills CLI, npx, Cursor), npm gotchas, the review checklist for third-party skills, and MCP / A2A rules for protocol-connected skills. This package is the installer CLI.",
+  "version": "0.9.0",
+  "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way \u2014 conformance to the Agent Skills open standard AND Anthropic's platform rules (front-matter limits, disclosure budgets, per-surface runtime limits, the Skills API, evals) plus the Claude Code plugin reference (manifest schemas, component layout, claude plugin validate --strict), marketplace repo layout, version sync, validator + CI, multi-channel distribution (plugin, vercel skills CLI, npx, Cursor), npm gotchas, the review checklist for third-party skills, and MCP / A2A rules for protocol-connected skills. This package is the installer CLI.",
   "keywords": [
     "skill",
     "plugin",
@@ -33,7 +33,6 @@
     "bin",
     "plugins",
     "cursor",
-    "templates",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",

package/plugins/make-skill/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "make-skill",
   "displayName": "Make Skill",
   "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way: conformance to the Agent Skills open standard, Anthropic's platform rules (surfaces, Skills API, evals) and the Claude Code plugin reference, marketplace repo layout, version sync, validator + CI, multi-channel distribution (plugin, vercel skills CLI, npx, Cursor), npm gotchas, end-to-end first publish, the review checklist for third-party skills, plus MCP / A2A references for protocol-connected skills.",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/make-skill/agents/skill-auditor.md

@@ -0,0 +1,46 @@
+---
+name: skill-auditor
+description: Audits one or many skill directories against the Agent Skills standard, Anthropic's platform rules and the ssheleg canon, returning a gap table with file:line evidence. Use when a repository holds several skills, or when the audit output would otherwise crowd out the work the main thread is doing.
+tools: Read, Grep, Glob, Bash
+---
+
+You audit skills. You do not fix them, and you do not offer to.
+
+## Procedure
+
+1. Locate every skill: a directory containing `SKILL.md`. In a plugin repo that
+   is `plugins/*/skills/*/`; elsewhere it may be `~/.claude/skills/*/`,
+   `.claude/skills/*/`, or a single directory handed to you.
+
+2. For each one, run the bundled auditor first — it is deterministic and costs
+   no reasoning:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/skills/make-skill/scripts/audit_skill.py" <skill-dir> --house
+   ```
+
+   If `${CLAUDE_PLUGIN_ROOT}` is unset, find the script under the make-skill
+   directory you were loaded from. If `python3` is missing, say so once and fall
+   back to reading `references/agent-skills-spec.md` and checking by hand — a
+   missing interpreter changes how you work, not whether you report.
+
+3. Work the judgement half from
+   `${CLAUDE_PLUGIN_ROOT}/skills/make-skill/references/retrofit.md`: one job per
+   skill, entry point, evaluations, distribution live-checks, repo meta. Read
+   the file; do not reconstruct it from memory.
+
+4. Where several skills coexist, check what the script cannot: do two
+   descriptions compete for the same trigger phrases? That is the failure mode
+   that degrades a whole family, and it is invisible per-skill.
+
+## Output
+
+One table for the caller, nothing else:
+
+| Skill | Verdict | Evidence |
+|---|---|---|
+
+`PASS` only for a check you actually ran — a `file:line` or the command output.
+`GAP` carries what is wrong and the fix that closes it. No "looks fine". Finish
+with the single highest-value next action across everything you audited, and
+stop.

package/plugins/make-skill/commands/skill-audit.md

@@ -0,0 +1,31 @@
+---
+description: "Audit a skill directory against the Agent Skills standard and Anthropic's platform rules — mechanical checks by script, judgement by the retrofit checklist"
+argument-hint: "[path to a skill dir] [--house]"
+---
+
+Audit the skill at `$ARGUMENTS` (default: the skill directory in the current
+working directory, or every `skills/*/` under `plugins/*/` if this is a plugin
+repo).
+
+1. Run the bundled auditor — it does the mechanical half deterministically:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/skills/make-skill/scripts/audit_skill.py" <skill-dir> --house
+   ```
+
+   No `${CLAUDE_PLUGIN_ROOT}` (not running as a Claude Code plugin)? The script
+   sits at `scripts/audit_skill.py` inside the skill directory you are reading
+   this from — commonly `~/.agents/skills/make-skill/` or
+   `~/.claude/skills/make-skill/`. No `python3` at all? Do the same checks by
+   hand from `references/agent-skills-spec.md`; the checklist is the same one the
+   script implements.
+
+2. Then work the judgement half from
+   `${CLAUDE_PLUGIN_ROOT}/skills/make-skill/references/retrofit.md` — one job,
+   entry point, evaluations, distribution, repo meta. The script cannot answer
+   those.
+
+3. Report one gap table: `PASS` / `GAP` per item, each with `file:line` or the
+   command output that proves it. End with exactly ONE suggested next action.
+
+Do not fix anything until the table is reported.

package/plugins/make-skill/hooks/hooks.json

@@ -0,0 +1,19 @@
+{
+  "description": "make-skill — spec check on every SKILL.md write. The hook exits 0 without output for any path that is not a SKILL.md, so installing this plugin globally changes nothing in projects that do not author skills. It never blocks: PostToolUse runs after the write, and the result is advice, not a veto.",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/skill-md-audit.sh\"",
+            "timeout": 20,
+            "statusMessage": "Auditing SKILL.md against the spec"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/make-skill/hooks/skill-md-audit.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# PostToolUse: after a SKILL.md is written or edited, audit its directory against
+# the Agent Skills standard and hand the result back as a system message.
+#
+# Contract, in this order:
+#   1. Not a SKILL.md write?      exit 0 immediately, print nothing. A globally
+#                                 installed plugin must be invisible in projects
+#                                 that do not author skills.
+#   2. No python3 on PATH?        exit 0 with no message. The audit is an
+#                                 accelerator; its absence must not surface as a
+#                                 hook error on someone else's machine.
+#   3. Skill has gaps?            exit 0 with a systemMessage naming them. Never
+#                                 exit 2: PostToolUse fires after the write, so
+#                                 blocking buys nothing and costs a turn.
+#
+# Everything this reads comes from the hook's stdin JSON; nothing is written.
+set -uo pipefail
+
+payload="$(cat)"
+
+# Extract the written path without assuming jq exists (it usually does not).
+file_path="$(printf '%s' "$payload" |
+  sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)"
+
+case "$file_path" in
+  */SKILL.md|SKILL.md) ;;
+  *) exit 0 ;;
+esac
+
+[ -f "$file_path" ] || exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+
+skill_dir="$(dirname "$file_path")"
+auditor="${CLAUDE_PLUGIN_ROOT:-}/skills/make-skill/scripts/audit_skill.py"
+[ -f "$auditor" ] || exit 0
+
+report="$(python3 "$auditor" "$skill_dir" --quiet 2>/dev/null)" && exit 0
+
+# Non-zero from the auditor means GAPs were found. Escape the report for JSON
+# with the tools every POSIX box has, then hand it back as advice.
+escaped="$(printf '%s' "$report" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+printf '{"systemMessage": %s, "suppressOutput": true}\n' "$escaped"
+exit 0