@ssheleg/make-skill 0.8.1 → 0.9.1

package/plugins/make-skill/skills/make-skill/assets/agent.template.md

@@ -0,0 +1,33 @@
+---
+name: agent-name-here
+description: What this agent does and WHEN the main thread should delegate to it. Third person, concrete triggers — the same selection problem a skill description solves.
+tools: Read, Grep, Glob, Bash
+# Optional: model, effort, maxTurns, disallowedTools, memory, background,
+#           isolation: "worktree"  (only value accepted)
+# REJECTED for plugin-shipped agents: hooks, mcpServers, permissionMode
+---
+
+You <one sentence: the single job>. You do not <the adjacent job you must refuse>.
+
+## Procedure
+
+1. Deterministic step first — run the bundled script rather than reasoning your
+   way to the same answer:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/skills/SKILL_NAME/scripts/SCRIPT.py" <target>
+   ```
+
+   No `${CLAUDE_PLUGIN_ROOT}`? You are not running as a Claude Code plugin —
+   find the script under the skill directory you were loaded from. Interpreter
+   missing? Say so once and do the checks by hand from the reference; a missing
+   tool changes how you work, not whether you report.
+
+2. Judgement steps, each naming the reference file that carries the rules. Read
+   the file; do not reconstruct it from memory.
+
+## Output
+
+Exactly what the caller needs and nothing else — a table, a verdict, or a patch.
+Evidence for every claim (`file:line` or command output). Finish with ONE next
+action and stop.

package/plugins/make-skill/skills/make-skill/assets/command.template.md

@@ -0,0 +1,32 @@
+---
+description: "One line the user sees in the / menu — what it does, not how it works"
+argument-hint: "[what to pass] [--flag]"
+---
+
+<!--
+Two rules this skeleton exists to enforce:
+
+  1. NEVER name this file after a skill directory in the same plugin. Commands
+     are skills now: `commands/x.md` beside `skills/x/` registers /x twice, the
+     skill wins, and the command is unreachable always-on token cost.
+  2. ALWAYS quote `argument-hint`. A bare [a | b] is a YAML flow sequence; one
+     comma inside it drops the whole frontmatter block, leaving a command with
+     no description and no warning.
+-->
+
+Do <the task> for `$ARGUMENTS`.
+
+1. The deterministic part, by script:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/skills/SKILL_NAME/scripts/SCRIPT.py" $ARGUMENTS
+   ```
+
+   Not running as a Claude Code plugin, so `${CLAUDE_PLUGIN_ROOT}` is unset? The
+   script is in the skill directory this file was installed beside. No
+   interpreter? Fall back to the manual procedure in the reference and say that
+   you did.
+
+2. The judgement part, from `references/FILE.md`.
+
+3. Report: what was checked, what the verdict is, and ONE next action.

package/plugins/make-skill/skills/make-skill/assets/hooks.template.json

@@ -0,0 +1,32 @@
+{
+  "description": "PLUGIN_NAME — one sentence on what these hooks do, and the sentence that matters to a reviewer: when they no-op. A globally installed plugin must be invisible in projects that do not use it.",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/HOOK_SCRIPT.sh\"",
+            "timeout": 20,
+            "statusMessage": "What the user sees while this runs"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/SESSION_SCRIPT.sh\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -180,6 +180,13 @@ if written carelessly.
 - **Vision is available**: rendering an input to images and letting the agent look
   at it beats describing a layout in prose.
 
+Worked example: this skill's own `scripts/audit_skill.py`. It is stdlib-only so
+it runs wherever the skill landed, prints `file:line` evidence rather than
+verdicts, handles its own missing-file and bad-frontmatter cases, and its first
+run flagged a false positive on the very document that teaches the anti-pattern —
+which is why it now ignores quoted spans. Hooks, subagents and commands that wrap
+it, plus the fallbacks they owe, are in `references/host-capabilities.md`.
+
 ## Evaluation and iteration — evals before prose
 
 **Build the evaluations before writing extensive documentation.** Otherwise the

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

@@ -48,10 +48,13 @@ the shape from `ssheleg/super-ux`:
 ├── .claude-plugin/marketplace.json     # root manifest, plugins[0].source: ./plugins/<name>
 ├── plugins/<name>/
 │   ├── .claude-plugin/plugin.json      # ONLY the manifest lives in .claude-plugin/
-│   └── skills/<skill>/SKILL.md  +  references/*.md (+ scripts/, assets/)
-│       (commands/*.md too — but never named after a skill)
+│   ├── skills/<skill>/SKILL.md  +  references/*.md  +  scripts/  +  assets/
+│   │                                   # skeletons live HERE, not at the repo root:
+│   │                                   # only the skill dir travels on every channel
+│   ├── hooks/hooks.json + *.sh         # Claude Code only — see host-capabilities.md
+│   ├── agents/*.md                     # Claude Code only
+│   └── commands/*.md                   # never named after a skill
 ├── cursor/rules/*.mdc                  # if agent-rules make sense for Cursor
-├── templates/*.md                      # skeletons (NEVER name one SKILL.md)
 ├── bin/<name>.js + package.json        # npx installer (zero-dep Node)
 ├── test/validate.py                    # consistency validator (stdlib only)
 ├── test/evals/                         # triggers.json + scenarios.json (data, run by a human)
@@ -59,15 +62,23 @@ the shape from `ssheleg/super-ux`:
 ├── install.sh                          # POSIX fallback
 ├── README.md (English-first), CHANGELOG.md, LICENSE (MIT)
 ├── CONTRIBUTING.md + SECURITY.md       # public repo: how to check work, where to report
+├── SKILL-CARD.md                       # the enterprise registry entry + risk-table pass
 └── docs/superpowers/{specs,plans}/
 ```
 
 **Public-repo floor** (validator-enforced): a README saying what it does before
 how to install it, **English-first** — Russian belongs in trigger phrases, where
 it changes whether the skill fires; `CONTRIBUTING.md` with the offline commands
-that verify a change; `SECURITY.md` naming a private reporting channel and what
-the installers touch. A skill is text an agent executes, so "review before
-installing" belongs in writing.
+that verify a change; `SECURITY.md` naming a private reporting channel and every
+path that executes, hooks first; `SKILL-CARD.md` answering the enterprise
+registry fields and the risk table honestly. A skill is text an agent executes,
+so "review before installing" belongs in writing — and anything that runs
+without being asked belongs at the top of it.
+
+**What travels where.** Only `skills/<skill>/` reaches non-Claude channels, so
+scripts and skeletons live inside it. `hooks/`, `agents/` and `commands/` reach
+Claude Code alone: they are accelerators, and the skill body owes each one a
+written fallback (`references/host-capabilities.md`).
 
 **Version sync (hard rule):** `marketplace.json`, `plugin.json`, `package.json`
 and the top CHANGELOG entry carry the SAME semver, bumped together; the validator
@@ -295,8 +306,12 @@ claude plugin update <name>@<name>             # full id required
 4. Conventional commit; push; confirm CI `success`; tag `v<ver>` and push the tag;
    `gh release create` from the CHANGELOG section (or let the release workflow
    below do it).
-5. npm publish if applicable (human 2FA the first time); e2e `npx <name>@<ver>`
-   from a non-repo cwd.
+5. **npm publishes itself** once CI publishing is armed (launch checklist step
+   9): the `v*` tag triggers it, with provenance, skipping a version the
+   registry already has. A manual `npm publish` here is the fallback for a repo
+   that has not armed it yet — not the normal path, and leaving it as the
+   normal path is how a family ends up with a release step nobody performs and
+   everybody documents. Then e2e `npx <name>@<ver>` from a non-repo cwd.
 6. **Refresh THIS machine's global installs — always, as Definition of Done:**
    `claude plugin marketplace update <name>` → `claude plugin update
    <name>@<name>` → `npx skills update <name> --global --yes && rm -f

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

@@ -6,11 +6,27 @@ standard — including the no-argument `/make-skill` path, where a `SKILL.md`,
 
 ## Contents
 
+- Run the script first
 - How to report (the only acceptable verdict format)
-- The 13-item audit checklist
+- 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:
@@ -25,7 +41,7 @@ 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 13-item audit checklist
+## 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;
@@ -77,6 +93,13 @@ the evidence. Report the gap table before changing anything, then fix.
     `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