@ssheleg/make-skill 0.8.1 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## v0.9.1 — 2026-08-05
+
+### Fixed
+- **The release checklist told agents to publish npm by hand.** Step 5 of the
+  recurring-release checklist in `distribution.md` said "npm publish if
+  applicable (human 2FA the first time)" — contradicting the launch checklist's
+  own step 9, which arms CI publishing precisely so that is the *last* manual
+  publish. A `v*` tag now publishes; manual publish is named as the fallback
+  for a repo that has not armed CI yet.
+- `CONTRIBUTING.md` carried the same stale instruction for the family
+  catalogue, and now points at `test/check_pins.py`, the registry comparison
+  `sshlg-skills` gained in v0.20.0.
+
+## 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.

package/README.md

@@ -34,9 +34,16 @@ make a skill that turns our incident runbooks into a triage workflow
 /make-skill:make-skill audit ./skills/my-skill against the spec
 ```
 
-With no argument it 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
+…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.
 
@@ -77,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
@@ -125,16 +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 13-item checklist, what counts as evidence for a PASS, and the short form for a personal skill |
+| `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
 
@@ -201,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
 
@@ -211,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,9 +13,21 @@ 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:
-
+`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

package/cursor/rules/make-skill.mdc

@@ -114,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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.8.1",
-  "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.1",
+  "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.1",
+  "version": "0.9.1",
   "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

package/plugins/make-skill/skills/make-skill/SKILL.md

@@ -2,6 +2,11 @@
 name: make-skill
 description: Use when creating, upgrading, auditing, or publishing agent skills and Claude Code plugins - "make a skill" / "сделай скилл", "new skill" / "новый скилл", "wrap it in a plugin" / "заверни в плагин", "publish a skill" / "опубликуй скилл", "retrofit a skill to the standard" / "приведи скилл к стандарту", "does this skill match the spec" / "соответствует ли скилл стандарту", "plugin.json / marketplace.json" / "claude plugin validate fails" / "проверь плагин по документации Anthropic", "is this skill safe to install" / "безопасно ли ставить этот скилл" - or when a skill must reach an MCP server or another agent over A2A. Encodes the Agent Skills open standard AND Anthropic's platform rules (front-matter limits, disclosure budgets, Skills API surfaces, evals), the Claude Code plugin reference (manifest schemas, component layout, validate --strict), plus the proven ssheleg pipeline - marketplace layout, version sync, validator+CI, multi-agent distribution, npm gotchas, end-to-end first publish.
 license: MIT
+compatibility: Authoring works on any agent. The bundled scripts/ need python3. Publishing steps need git, gh, node and npm; the plugin gates need the claude CLI. Not usable on the Claude API surface, which has no network and no runtime package install.
+metadata:
+  author: ssheleg
+  version: "0.9.1"
+  homepage: https://github.com/ssheleg/make-skill
 ---
 
 # make-skill — Create, Retrofit, and Ship Skills the Proven Way
@@ -20,6 +25,7 @@ Copy from a working repo (usually `~/DATA/<name>`): **`ssheleg/super-ux`**
 | `references/surfaces.md` | shipping anywhere but Claude Code — Skills API upload/versions/8-per-request, claude.ai zip, the no-network / no-install limits |
 | `references/enterprise.md` | installing someone else's skill, or governing a fleet — risk tiers, review checklist, approval gates, lifecycle, recall limits |
 | `references/retrofit.md` | auditing an existing skill/repo — the 13-item checklist, the evidence rules, the short form for personal skills |
+| `references/host-capabilities.md` | shipping a **hook, subagent, command, script or MCP dependency** — what each buys and costs, hook events/exit codes, and the degradation clauses that keep the skill working without them |
 | `references/claude-code-plugin.md` | anything shipping as a **Claude Code plugin/marketplace** — manifest schemas, component layout, LSP/monitors, path variables, `validate` failures |
 | `references/distribution.md` | the repo layout, publishing, channels, releases |
 | `references/mcp.md` | the skill calls/wraps/documents an **MCP** server, or you're choosing skill vs server |
@@ -121,15 +127,45 @@ House additions on top of the spec:
 - Never overwrite user data: seed only when absent; overwrite only behind
   `--force`.
 
+### Degradation contract (every skill that touches a host capability)
+
+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, more slowly.** Write the three cases into the body, in the agent's words, at
+the point it will need them (shapes and wording:
+`references/host-capabilities.md`):
+
+- **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 directory — so give the path for each channel.
+- **Recommended plugin/skill absent**: say once what is degraded, 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.
+
+A fallback you know but did not write is not a fallback.
+
+### Working examples this skill ships — copy these, not your memory
+
+`scripts/audit_skill.py` audits ANY skill dir (stdlib; the mechanical half of a
+Retrofit). Beside it: `hooks/` (PostToolUse, exits 0 silently unless a `SKILL.md`
+was written), `commands/skill-audit.md` (deliberately NOT the skill's name),
+`agents/skill-auditor.md`, and six skeletons —
+`assets/SKILL.template.md`, `assets/plugin.template.json`,
+`assets/marketplace.template.json`, `assets/hooks.template.json`,
+`assets/agent.template.md`, `assets/command.template.md`.
+
 ## Create (personal)
 
-`~/.claude/skills/<name>/SKILL.md` following the authoring rules — done. No
-repo, no versioning; loads next session. Mention Promote as the upgrade path.
+`~/.claude/skills/<name>/SKILL.md` per the authoring rules — done. No repo, no
+versioning; loads next session. Mention Promote as the upgrade path.
 
 Needs hooks, an agent, or an MCP server too, still with no repo? Add
 `.claude-plugin/plugin.json` to that same folder — Claude Code loads it as
-`<name>@skills-dir` next session, no marketplace, no install
-(`claude plugin init <name> --with hooks mcp` scaffolds it).
+`<name>@skills-dir` next session (`claude plugin init <name> --with hooks mcp`
+scaffolds it).
 
 ## Create (distributable)
 
@@ -159,12 +195,11 @@ writing the first file.** What holds regardless:
 
 Take it ALL the way: GitHub + CI green + npm published + verified installs, no
 half-done handoffs. Only the first publish needs a human (npm 2FA); **arming CI
-publishing is part of shipping**, so the second one does not.
-
-**The 11-step sequence is in `references/distribution.md` → *First publish*.**
-Everything green BEFORE publishing, and done = five VERIFIED facts: repo + CI
-green, npm resolvable via npx, plugin installed, skills-CLI discovery working,
-next tag publishing without a human.
+publishing is part of shipping**, so the second one does not. **The 11-step
+sequence is in `references/distribution.md` → *First publish*.** Everything
+green BEFORE publishing; done = five VERIFIED facts: repo + CI green, npm
+resolvable via npx, plugin installed, skills-CLI discovery working, next tag
+publishing without a human.
 
 ## Retrofit (bring an existing skill/repo up to standard)
 
@@ -173,12 +208,13 @@ evidence — a `file:line` or the output of the command you actually ran. "Looks
 fine" is not a verdict, and neither is a PASS on a check that was reasoned about
 instead of executed.
 
-**The 13-item checklist is in `references/retrofit.md` — open it before
-auditing.** It covers, in order: the spec floor, the Anthropic plugin floor,
-surface honesty, one-job, entry point, layout and version sync, validator and
-CI, evaluations, README, distribution live-checks, repo meta, gotcha compliance,
-protocol dependencies. For a PERSONAL skill only three of them apply (spec
-floor, one-job, entry point) — that file says which.
+**Run `scripts/audit_skill.py <dir> --house` first** — it does the mechanical
+half deterministically — **then work the 14-item checklist in
+`references/retrofit.md`**, which covers the spec floor, the Anthropic plugin
+floor, surface honesty, one-job, entry point, layout and version sync, validator
+and CI, evaluations, README, distribution live-checks, repo meta, gotchas,
+protocol dependencies, and host capabilities with their fallbacks. For a
+PERSONAL skill only three items apply — that file says which.
 
 **Then:** report the gap table, fix everything fixable now, bump a minor/patch
 version, run the release checklist.
@@ -192,29 +228,25 @@ AFTER the plugin install is verified — duplicate listings confuse agents.
 
 ## Distribution matrix
 
-Five filesystem channels: **Claude Code plugin** (`marketplace add` → `install
-<name>@<name>`), **vercel skills CLI** (`npx skills add <owner>/<repo>`, 70+
-agents, reads `marketplace.json`), **npx** (`npx github:<owner>/<repo>`),
-**Cursor** (skills CLI `--agent cursor --global`, or `.cursor/rules/*.mdc`),
-**umbrella family repo** (`ssheleg/sshlg-skills`). Anthropic's own surfaces —
-Skills API upload (workspace-wide, 8 per request) and claude.ai zip (per user,
-no admin push) — are separate deployments syncing with nothing:
+Five filesystem channels — Claude Code plugin, vercel skills CLI (70+ agents,
+reads `marketplace.json`), npx, Cursor, umbrella family repo — with the exact
+flags in **`references/distribution.md`; read it before publishing, adding a
+channel, or auditing distribution.** Anthropic's own surfaces (Skills API
+upload, claude.ai zip) are separate deployments syncing with nothing:
 `references/surfaces.md`.
 
-**Read `references/distribution.md` before publishing, adding a channel, or
-auditing distribution.** Two rules survive without it: **one channel per agent**
-(never `claude-code` via the skills CLI when a plugin is installed), and **e2e
-`npx` from a non-repo cwd**.
+Two rules survive without opening either: **one channel per agent** (never
+`claude-code` via the skills CLI when a plugin is installed), and **e2e `npx`
+from a non-repo cwd**.
 
 ## Installing someone else's skill
 
 A skill is instructions an agent executes plus code it runs without reading —
 installing one is installing software. Anything not written here gets the
-`references/enterprise.md` review first: scripts read end to end, network calls
-and credentials grepped for, instructions checked for "ignore previous rules",
-hidden actions, or data routed outward. Highest-risk shape: a skill that fetches
-instructions from a URL — that content changes after your review. Same file for
-the fleet rules (approval gates, lifecycle, recall limits).
+`references/enterprise.md` review first: every file read, network calls and
+credentials grepped for, instructions checked for "ignore previous rules",
+hidden actions, or data routed outward. Highest-risk shape: a skill fetching
+instructions from a URL — that content changes after your review.
 
 ## Protocol-connected skills (MCP / A2A)
 
@@ -245,34 +277,31 @@ Non-negotiables for any such skill:
 
 ## Gotchas (each cost a debugging round)
 
-- **npm publishing has its own trap list** — 2FA/EOTP, the name-similarity 403
-  `npm view` can't predict, auth failures masked as 404 on PUT, read-replica lag
-  after a first scoped publish, `npx` resolving locally inside the package's own
-  repo. Fixes in `references/distribution.md` → **read it before any publish.**
+- **npm publishing has a five-trap list** — 2FA/EOTP, a name-similarity 403 that
+  `npm view` cannot predict, auth failures masked as 404, read-replica lag, and
+  `npx` resolving locally inside the package's own repo. Each with its fix in
+  `references/distribution.md` → **read it before any publish.**
 - **A stray `SKILL.md` anywhere in the repo ships as a REAL skill** — the skills
   CLI discovers every one in the tree, so `templates/SKILL.md` lands in every
   agent as a placeholder (seen live: a skill named `<skill-name>`). Name
   skeletons `SKILL.template.md`, have the validator reject any `SKILL.md`
   outside the skill dirs, verify with `npx skills add <repo> --list`.
-- **Quote every `argument-hint`.** Bare `[a | b]` is a YAML flow sequence — one
-  comma drops the whole front-matter block, leaving a command with no
-  description and no warning.
-- **Never name a `commands/<x>.md` after a `skills/<x>/`** — same name, two
-  components: the skill wins and the command is unreachable always-on cost
-  (~100 tok/session here). Check with `claude plugin details`.
+- **Commands: quote every `argument-hint`** (bare `[a | b]` is a YAML flow
+  sequence — one comma drops the whole front-matter block, silently) and **never
+  name one after a skill** in the same plugin (both claim `/<x>`, the skill wins,
+  the command is unreachable always-on cost). Details:
+  `references/host-capabilities.md`.
 - **Writing the installer or validator?** Four more traps (piped-stdin readline,
   raw-mode pickers, ANSI literals, python 3.9 drift) are in
   `references/distribution.md` → *Installer implementation traps*.
 - **gh auth status may lie** (invalid-token report while git+ssh works): attempt
   the operation before declaring it blocked.
-- **Duplicate-shadow: one channel per agent — and the shadow regrows.** A plugin
-  install AND a plain `~/.claude/skills/<name>` copy = two listings, and the
-  plain (usually STALE) one wins. `npx skills add|update … --global` recreates
-  that path **even when `claude-code` was never targeted**, so the prune belongs
-  in the update command: `npx skills update <name> --global --yes && rm -f
-  ~/.claude/skills/<name>`.
-- **Plugin commands need the full `<name>@<name>`:** `claude plugin update
-  <name>` → "Plugin not found". Same for install.
+- **Duplicate-shadow: the stale copy wins, and it regrows.** A plugin install
+  plus a plain `~/.claude/skills/<name>` copy = two listings; `npx skills
+  add|update … --global` recreates that path **even when `claude-code` was never
+  targeted**, so the prune belongs inside the update command: `npx skills update
+  <name> --global --yes && rm -f ~/.claude/skills/<name>`. Plugin commands also
+  need the full id — `claude plugin update <name>` answers "Plugin not found".
 - **A pinned `version` you forget to bump freezes every user.** The version is
   the update cache key: twenty commits under `0.6.1` and `/plugin update` still
   says "already at the latest version". (Omitting it from both manifests is