@ssheleg/make-skill 0.8.0 → 0.9.0

package/plugins/make-skill/skills/make-skill/references/host-capabilities.md

@@ -0,0 +1,218 @@
+# Host capabilities — hooks, agents, commands, and what happens without them
+
+**Load this when:** deciding whether a skill should ship a hook, a subagent, a
+command, an MCP server or a script — or when writing the degradation clauses that
+keep it working where those do not exist.
+
+Sources: [Claude Code hooks reference](https://code.claude.com/docs/en/hooks) and
+the [plugins reference](https://code.claude.com/docs/en/plugins-reference)
+(*read 2026-08-03, Claude Code 2.1.212*), plus `references/claude-code-plugin.md`
+for the manifest side.
+
+## Contents
+
+- The rule: accelerator, never precondition
+- What to reach for, and what it costs
+- Hooks — events, handlers, matchers, exit codes
+- Writing a hook that is invisible when idle
+- Subagents
+- Commands
+- Scripts
+- MCP servers and other plugins as dependencies
+- The three degradation cases, written out
+- Checklist
+
+## The rule: accelerator, never precondition
+
+Everything on this page exists only inside Claude Code. A skill that *needs* one
+of them is broken on Cursor, Codex, the skills CLI, the Claude API and claude.ai
+— which is most of where skills run. So:
+
+> **Every host capability is an accelerator with a stated fallback. The skill
+> must complete its job without it, more slowly and with less polish.**
+
+"Stated" is the operative word: the fallback goes in the skill body, in the words
+the agent will read at the moment the capability is missing. A fallback you know
+but did not write is not a fallback.
+
+## What to reach for, and what it costs
+
+| Capability | Buys you | Costs | Reach for it when |
+|---|---|---|---|
+| `scripts/` | determinism, and output instead of code in context | none until run | the agent re-derives the same logic every run |
+| `hooks/` | enforcement at the moment of the action | runs on the user's machine, every matching tool call | a rule matters more than an instruction can guarantee |
+| `agents/` | a job done in a separate context window | ~100 always-on tokens per agent | the work would otherwise crowd out the main thread |
+| `commands/` | a user-typed entry point with arguments | ~50–100 always-on tokens | a human, not the model, decides when it runs |
+| `mcpServers` | live capability (network, credentials, a process) | a server to install, auth to hold | instructions cannot do it — see `references/mcp.md` |
+| `lspServers`, `monitors`, `themes`, `outputStyles`, `workflows` | narrow, real, and rarely what a skill wants | always-on where they load | you can name the user who asked for it |
+| `userConfig` | values prompted at enable time | a prompt in everyone's install | the skill genuinely cannot guess (a path, a workspace id) |
+
+Everything in that table is Claude-Code-only. `scripts/` is the exception that
+travels: it lives inside the skill directory, so every channel ships it.
+
+## Hooks — events, handlers, matchers, exit codes
+
+Plugin hooks live in `hooks/hooks.json` at the plugin root (auto-discovered; a
+manifest key is only needed for a custom path). Shape:
+
+```json
+{ "hooks": { "PostToolUse": [ { "matcher": "Write|Edit",
+    "hooks": [ { "type": "command", "shell": "bash",
+                 "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/check.sh\"",
+                 "timeout": 20 } ] } ] } }
+```
+
+**Events worth a skill's attention** (the full set is larger):
+
+| Event | Fires | Blocks? | Use for |
+|---|---|---|---|
+| `SessionStart` | session begins/resumes (`startup\|resume\|clear\|compact\|fork`) | no | seeding state, `additionalContext` |
+| `UserPromptSubmit` | before the model sees the prompt | yes | injecting context, refusing a prompt |
+| `PreToolUse` | before a tool runs | yes — `permissionDecision: deny` | guarding a destructive action |
+| `PostToolUse` | after a tool succeeds | no | validating what was just written |
+| `Stop` / `SubagentStop` | a turn or subagent finishes | yes | completion gates |
+| `SessionEnd` | session ends | no | cleanup (1.5s shared budget) |
+
+**Handler types:** `command` (a script — the portable one), `http`, `mcp_tool`,
+`prompt`, `agent`. `command` takes `shell` (`bash`/`powershell`) in shell form,
+or `args` for exec form with no shell tokenization.
+
+**Matchers** are exact strings or `A|B` lists; anything with other characters is
+an unanchored regex. Tool names are what you match (`Bash`, `Write`,
+`mcp__server__tool`). A plugin's OWN MCP server is matched as
+`mcp__plugin_<plugin>_<server>__<tool>`, and an `mcp_tool` hook names the server
+as `plugin:<plugin>:<server>` — the bare key never fires. Narrow further with
+`if`, a permission rule: `"if": "Bash(git commit *)"`.
+
+**Exit codes are the contract:**
+
+| Exit | Meaning |
+|---|---|
+| `0` | success; stdout is parsed as JSON for structured output |
+| `2` | blocking error; **stderr goes to the model**, stdout is ignored |
+| other | non-blocking error; the action proceeds, the transcript shows a hook error |
+
+Structured output on exit 0: `systemMessage` (shown to the user),
+`additionalContext` (injected for the model), `decision: "block"` with `reason`,
+`permissionDecision` for `PreToolUse`, `suppressOutput`, `continue: false`.
+
+**Environment:** `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`,
+`${CLAUDE_PROJECT_DIR}` substitute in the command and are exported. Quote them —
+a space in the install path otherwise splits the command.
+
+## Writing a hook that is invisible when idle
+
+A plugin installed globally fires its hooks in every project. Two rules keep that
+from being a nuisance, and both belong in the `description` field of
+`hooks.json`, where a reviewer reads them:
+
+1. **Exit 0 with no output the moment the event is not yours.** Wrong tool, wrong
+   path, no project marker file → `exit 0` before doing any work. This is why
+   `agent-sync`'s hooks open by checking for `.claude/agent-sync.json`.
+2. **Degrade instead of erroring.** No interpreter, missing script, unparsable
+   input → `exit 0` silently. A hook that reports its own absence as a failure
+   trains the user to disable hooks.
+
+Block (`exit 2`) only where blocking is the point, and only on `PreToolUse` or
+another event that actually blocks. On `PostToolUse` the write already happened;
+advice via `systemMessage` is worth more than a veto that costs a turn.
+
+Ship the script with a shebang and `chmod +x`, and keep it dependency-free —
+`jq` is not installed everywhere, and a hook is a bad place to discover that.
+
+## Subagents
+
+`agents/*.md` with `name` and `description`; optional `model`, `effort`,
+`maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`,
+`isolation: "worktree"`. **`hooks`, `mcpServers` and `permissionMode` are
+rejected** for plugin-shipped agents. They appear as `<plugin>:<agent>`.
+
+A subagent earns its always-on cost when the work is *voluminous and separable* —
+an audit across twenty skills, a survey, a long verification — because its output
+is a summary while its reading stays in its own context. It does not earn it when
+the main thread needs the intermediate detail anyway.
+
+Fallback: on any other host there are no subagents. The skill body must describe
+the same procedure inline, so a Cursor session does the work in one context.
+
+## Commands
+
+`commands/*.md`, frontmatter `description` plus a **quoted** `argument-hint`;
+body receives `$ARGUMENTS`. Two rules cost a debugging round each:
+
+- **Never name a command after a skill in the same plugin.** Commands are skills
+  now: both claim `/<name>`, the skill wins, the command is unreachable always-on
+  cost visible only in `claude plugin details`.
+- **Quote `argument-hint`.** Bare `[a | b]` is a YAML flow sequence; a comma
+  inside it drops the entire frontmatter block, leaving a command with no
+  description and no warning.
+
+Fallback: elsewhere there is no `/command`. The skill's own description must
+carry the trigger phrases that reach the same behavior in plain language.
+
+## Scripts
+
+The one accelerator that travels. Keep it inside the skill directory
+(`scripts/`), stdlib-only, and invoke it by a path the agent can actually
+resolve:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/<skill>/scripts/x.py" <target>   # Claude Code
+python3 ~/.agents/skills/<skill>/scripts/x.py <target>                 # skills CLI
+python3 ~/.claude/skills/<skill>/scripts/x.py <target>                 # plain install
+```
+
+**The absolute path differs per channel**, so the instruction that survives is
+"run the script from the skill directory you just read this file from", with
+`${CLAUDE_PLUGIN_ROOT}` offered as the Claude Code convenience. State the
+no-interpreter fallback too: the manual procedure, in the reference that the
+script implements.
+
+## MCP servers and other plugins as dependencies
+
+A skill may *use* an MCP server or a sibling skill; it may not *require* one
+silently. Declare it in frontmatter `compatibility`, and write the branch:
+
+- **Server present** → name the tool by discovery, never a hardcoded string
+  (`references/mcp.md`).
+- **Server absent** → say so once, name what is degraded, and continue with the
+  manual path. Never loop on 401s; interactive auth is a human step.
+- **Sibling skill absent** (`super-ux`, `agent-sync`, …) → the dependent stage
+  still runs, with its quality reduced and that reduction stated. A pipeline that
+  refuses to start because an optional companion is missing is a broken pipeline.
+
+Claude Code's manifest `dependencies` field can express a hard requirement
+between plugins. Use it only when the skill genuinely cannot function — and know
+that it means nothing on any other host.
+
+## The three degradation cases, written out
+
+Put these in the skill body, in this shape:
+
+```markdown
+## Degradation
+
+- **Not Claude Code** (Cursor, Codex, skills CLI, API): hooks, subagents and
+  `/commands` do not exist. Run <procedure> inline; the bundled `scripts/` still
+  work wherever `python3` does.
+- **Recommended plugin absent** (<name>): <what is lost>. Continue with
+  <manual path>, and say once that the result is <weaker in this way>.
+- **Tool or interpreter absent** (`python3`, `gh`, `npm`, an MCP server): state
+  it once, fall back to <the by-hand procedure>, never retry in a loop.
+```
+
+Three lines, one per axis. They are what a reader checks before installing, and
+what the agent reads at the exact moment something is missing.
+
+## Checklist
+
+- [ ] Every host capability the skill ships has a written fallback in the body
+- [ ] `hooks.json` `description` says when the hooks no-op
+- [ ] Hook scripts exit 0 silently on "not mine" and on a missing interpreter
+- [ ] `PostToolUse` advises (`systemMessage`), `PreToolUse` blocks — not the reverse
+- [ ] Hook commands quote `"${CLAUDE_PLUGIN_ROOT}"` and set a `timeout`
+- [ ] Hook scripts are executable, have a shebang, and need no `jq`
+- [ ] No command named after a skill; every `argument-hint` quoted
+- [ ] Plugin agents carry no `hooks` / `mcpServers` / `permissionMode`
+- [ ] Scripts are stdlib-only, inside the skill dir, invoked by a resolvable path
+- [ ] MCP and sibling-skill dependencies declared in `compatibility` with a branch

package/plugins/make-skill/skills/make-skill/references/retrofit.md

@@ -0,0 +1,114 @@
+# Retrofit — the audit procedure
+
+**Load this when:** auditing an existing skill, plugin or repo against this
+standard — including the no-argument `/make-skill` path, where a `SKILL.md`,
+`.claude-plugin/` or `plugins/*/skills/*/` in the current directory means Retrofit.
+
+## Contents
+
+- Run the script first
+- How to report (the only acceptable verdict format)
+- The 14-item audit checklist
+- Personal skills — the short form
+- After the audit
+
+## Run the script first
+
+The mechanical half is deterministic — do not reason your way through it:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/make-skill/scripts/audit_skill.py" <skill-dir> --house
+```
+
+`${CLAUDE_PLUGIN_ROOT}` is Claude Code's. On any other host the script sits at
+`scripts/audit_skill.py` inside the make-skill directory you are reading this
+from (`~/.agents/skills/make-skill/`, `~/.claude/skills/make-skill/`). No
+`python3` at all? Check items 1 and 9 below by hand against
+`references/agent-skills-spec.md` — the script implements that checklist and
+nothing more. Either way, the judgement items are yours.
+
+## How to report
+
+Audit first, fix second, in the same session. One verdict per item:
+
+| Verdict | Requires |
+|---|---|
+| **PASS** | the check was actually run — a command's output or a `file:line` |
+| **GAP** | what is wrong, the evidence, and the fix that closes it |
+
+"Looks fine" is not a verdict. Neither is a PASS on a check that was reasoned
+about rather than executed: `python3 test/validate.py`, `claude plugin validate
+… --strict`, `npx skills add <repo> --list` all produce output, and the output is
+the evidence. Report the gap table before changing anything, then fix.
+
+## The 14-item audit checklist
+
+1. **Spec floor** (`references/agent-skills-spec.md`): `name` charset + ≤64 +
+   equal to the directory + no `anthropic`/`claude` + no angle brackets;
+   `description` ≤1024, starts "Use when…", third person, English AND Russian
+   triggers, says what it does and when; no front-matter key outside spec ∪ host
+   extensions; body <500 lines and <5000 tokens; every `references/`,
+   `scripts/`, `assets/` file one level deep, linked from the body with a stated
+   load trigger, and a `## Contents` list past 100 lines. A skill can pass every
+   house rule and still be invalid upstream.
+2. **Anthropic floor** if it ships as a plugin
+   (`references/claude-code-plugin.md`): `claude plugin validate <plugin dir>
+   --strict` and `claude plugin validate . --strict` both exit 0; `$schema` and
+   `displayName` in the manifest and in the marketplace entry; components at the
+   plugin root, never inside `.claude-plugin/`; `claude plugin details <name>`
+   token cost worth paying every session.
+3. **Surface honesty** (`references/surfaces.md`): every runtime need — network,
+   packages, MCP server — declared in `compatibility`; no script assuming an
+   install the target surface forbids. A `pip install` in a workflow step is a
+   Claude Code skill claiming to be portable.
+4. **One job.** Two concerns → two skills plus a shared contract, and the
+   contract lives INSIDE each skill directory. Verify by installing through the
+   skills CLI and listing what actually arrived, not by reading the repo.
+5. **Entry point** exists and is idempotent: inspect state → repair what is
+   missing → status report → exactly ONE suggested next action, detected rather
+   than asked. Check the invocation for the channel it ships on (`/<skill>` from
+   a skills dir, `/<plugin>:<skill>` as a plugin).
+6. **Layout and manifests**: matches the tree in `references/distribution.md`;
+   version sync ×4 (×5 when `SKILL.md` carries `metadata.version`).
+7. **Validator**: present, green, and able to fail — run the negative test. CI
+   present, last run `success`, with `claude plugin validate --strict` as its own
+   job so an upstream outage cannot mask a house failure.
+8. **Evaluations** exist in `test/evals/` (`references/authoring.md`): ≥3
+   behavioral scenarios, a trigger set whose negatives are near-misses, both
+   classes on both sides of the train/validation split, coexistence checked
+   against the skills already installed, and a re-run on every model the skill
+   claims support for.
+9. **README**: badges (npm/CI/license), install + update matrix, English-first
+   prose, and the bundled `references/` listed so a reader sees what ships.
+10. **Distribution live-checks** (`references/distribution.md`): `npx --yes
+    skills add <repo> --list` lists ONLY real skills; `npx <name>` works from a
+    non-repo cwd if it is published; `.mdc` rules valid and free of relative
+    links.
+11. **Repo meta**: homepage, description and topics set on the forge; LICENSE
+    present and declared in the front matter and the marketplace entry;
+    CHANGELOG current; public repos also carry CONTRIBUTING.md and SECURITY.md.
+12. **Gotcha compliance**: the list in `SKILL.md`, plus the installer traps in
+    `references/distribution.md` when the repo ships a CLI or a validator.
+13. **Protocol dependencies** if it touches MCP or A2A (`references/mcp.md`,
+    `references/a2a.md`): dependency and protocol version in `compatibility`,
+    discovery instead of hardcoded tool names, the untrusted-output rule stated,
+    interactive auth handled as a human step rather than a retry loop.
+14. **Host capabilities and their fallbacks**
+    (`references/host-capabilities.md`) if it ships a hook, subagent, command or
+    MCP server: the degradation contract written in the body for all three axes
+    (not Claude Code / recommended plugin absent / tool absent); hooks that
+    exit 0 silently when the event is not theirs; `PostToolUse` advising rather
+    than blocking; commands quoted and never named after a skill; plugin agents
+    free of `hooks`, `mcpServers` and `permissionMode`.
+
+## Personal skills — the short form
+
+A skill in `~/.claude/skills/<name>/` has no repo, no manifests, no CI and no
+distribution, so items 1, 4 and 5 are the whole audit. Do not invent a release
+process for a file that loads next session.
+
+## After the audit
+
+Report the gap table, fix everything fixable now, bump a minor or patch version,
+and run the release checklist in `references/distribution.md`. A retrofit that
+ends in a list of things someone should do later is a report, not a retrofit.