@ssheleg/make-skill 0.10.0 → 0.11.1

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

@@ -40,6 +40,7 @@ but did not write is not a fallback.
 | 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 |
+| `bin/` | a bundled script reachable **by name** — Claude Code puts it on the Bash tool's PATH | none until run | a documented command must work without a path variable (see *Scripts*) |
 | `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 |
@@ -154,19 +155,42 @@ carry the trigger phrases that reach the same behavior in plain language.
 
 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:
+resolve.
+
+**The trap that costs the most here: `${CLAUDE_PLUGIN_ROOT}` does not work in a
+command you tell the agent to run.** It is substituted into skill, command and
+agent *text*, and it is exported to *hook and monitor* processes — but it is
+**not** in the Bash tool's environment. Measured on Claude Code 2.1.220:
 
 ```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
+$ echo "[${CLAUDE_PLUGIN_ROOT}]"
+[]
+$ python3 "${CLAUDE_PLUGIN_ROOT}/skills/x/scripts/x.py" .
+python3: can't open file '/skills/x/scripts/x.py': [Errno 2] No such file or directory
 ```
 
-**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.
+That failure is expensive out of proportion to its size: the agent was told to
+run a deterministic check, the check will not run, and reasoning through it
+instead — then reporting the result as if it had run — is the cheapest way out.
+
+**Ship a wrapper in the plugin's `bin/` instead.** Claude Code puts a plugin's
+`bin/` on the Bash tool's PATH while the plugin is enabled, so the script
+becomes reachable by name, with no variable in the command:
+
+```bash
+<plugin>-<verb> <target>          # Claude Code: bin/ is on PATH
+```
+
+Make the wrapper resolve its payload from **its own location** (`dirname "$0"`,
+following symlinks), never from an environment variable — then it also works
+copied, symlinked into an agents hub, or called by absolute path. Worked
+example: this plugin's `bin/make-skill-audit`.
+
+Everywhere else the absolute path differs per channel
+(`~/.agents/skills/<skill>/`, `~/.claude/skills/<skill>/`), so the instruction
+that survives is "run the script from the skill directory you just read this
+file from". State the no-interpreter fallback too: the manual procedure, in the
+reference that the script implements, and the items it leaves **NOT-RUN**.
 
 ## MCP servers and other plugins as dependencies
 
@@ -215,4 +239,6 @@ what the agent reads at the exact moment something is missing.
 - [ ] 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
+- [ ] No command the agent is told to RUN contains `${CLAUDE_PLUGIN_ROOT}` — it is
+      empty in the Bash tool; ship a `bin/` wrapper and call it by name
 - [ ] MCP and sibling-skill dependencies declared in `compatibility` with a branch

package/plugins/make-skill/skills/make-skill/references/mcp-ship.md

@@ -19,14 +19,14 @@ schema is dated by design.
 
 ## Contents
 
-- [Mounting into an existing web app](#mounting-into-an-existing-web-app)
-- [Auth middleware and a health endpoint](#auth-middleware-and-a-health-endpoint)
-- [Client configuration](#client-configuration)
-- [Debugging a client that will not connect](#debugging-a-client-that-will-not-connect)
-- [Publishing to the MCP Registry](#publishing-to-the-mcp-registry)
-- [Registry name formats and who may claim them](#registry-name-formats-and-who-may-claim-them)
-- [Automating publication](#automating-publication)
-- [Versioning](#versioning)
+- Mounting into an existing web app
+- Auth middleware and a health endpoint
+- Client configuration
+- Debugging a client that will not connect
+- Publishing to the MCP Registry
+- Registry name formats and who may claim them
+- Automating publication
+- Versioning
 
 ---
 

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

@@ -14,18 +14,33 @@ standard — including the no-argument `/make-skill` path, where a `SKILL.md`,
 
 ## Run the script first
 
-The mechanical half is deterministic — do not reason your way through it:
+The mechanical half is deterministic — do not reason your way through it. In
+Claude Code the plugin's `bin/` is on the Bash tool's PATH, so the auditor is
+reachable by name:
 
 ```bash
-python3 "${CLAUDE_PLUGIN_ROOT}/skills/make-skill/scripts/audit_skill.py" <skill-dir> --house
+make-skill-audit <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.
+On any other host, run the script it wraps — `scripts/audit_skill.py` inside the
+make-skill directory you are reading this from (`~/.agents/skills/make-skill/`,
+`~/.claude/skills/make-skill/`):
+
+```bash
+python3 <make-skill dir>/scripts/audit_skill.py <skill-dir> --house
+```
+
+**Do not build the command out of `${CLAUDE_PLUGIN_ROOT}`.** That variable is
+substituted into skill, command and agent *text*, but it is **not exported to
+the Bash tool's environment** — a command written around it expands to
+`/skills/...` and dies with "No such file or directory" (measured, Claude Code
+2.1.220). That failure is how a mechanical check turns into a reasoned-about
+PASS, which is the one outcome this file exists to prevent.
+
+No `python3` at all? Record items 1 and 9 as **NOT-RUN** with that reason and
+check them 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
 
@@ -35,11 +50,21 @@ Audit first, fix second, in the same session. One verdict per item:
 |---|---|
 | **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 |
+| **NOT-RUN** | the tool the check needs is absent — name the tool and the reason |
 
 "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 evidence.
+
+**NOT-RUN exists so that "I could not run this" has somewhere to go.** A
+checklist with only PASS and GAP forces an unrunnable check into one of them,
+and the cheaper lie is PASS. Item 1's `skills-ref validate` is the standing
+example: it installs from source only, so on most machines it is NOT-RUN, and
+saying so is the honest result. A NOT-RUN you did not try to resolve is still a
+gap in the audit — say what would make it runnable.
+
+Report the table before changing anything, then fix.
 
 ## The 14-item audit checklist
 
@@ -84,15 +109,17 @@ the evidence. Report the gap table before changing anything, then fix.
     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
+11. **Repo meta**: homepage, description and topics set on the forge (any
+    consistent homepage convention — do not "fix" a deliberate one); 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.
+    `references/mcp-ship.md` once a server is being shipped, `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

package/plugins/make-skill/skills/make-skill/scripts/audit_skill.py

@@ -30,6 +30,10 @@ import sys
 # --- limits, each with the authority that sets it --------------------------
 NAME_MAX = 64           # spec: name is 1-64 characters
 DESC_MAX = 1024         # spec: description is 1-1024 characters
+# House working limit: 5% under the cap. The description is the whole triggering
+# budget AND the field that must grow when a near-miss skill appears ("say what
+# it is NOT for"). A description at 98% of cap cannot absorb that sentence.
+DESC_TARGET = 970
 COMPAT_MAX = 500        # spec: compatibility is 1-500 characters
 BODY_MAX_LINES = 500    # spec + Anthropic: keep the body under 500 lines
 BODY_MAX_TOKENS = 5000  # spec + Anthropic: level-2 budget
@@ -171,7 +175,10 @@ def _check_name(a, fm, lines, dir_name, rel):
         a.gap("NAME_CHARSET", "name %r must be lowercase a-z0-9 with single internal "
               "hyphens — no uppercase, no leading/trailing or doubled hyphen" % name, rel, ln)
     else:
-        a.ok("NAME_CHARSET", "name %r is spec-legal" % name, rel, ln)
+        # Charset only. Saying "spec-legal" here would contradict NAME_RESERVED
+        # and NAME_XML below, and a PASS line quoted out of context is exactly
+        # how a wrong verdict acquires real command output as its evidence.
+        a.ok("NAME_CHARSET", "name %r uses a legal charset" % name, rel, ln)
     if name != dir_name:
         a.gap("NAME_DIR", "name %r != directory %r — the spec requires them to match, "
               "and the Skills API matches the uploaded top-level directory against it"
@@ -211,10 +218,24 @@ def _check_description(a, fm, lines, rel, house):
     else:
         a.ok("DESC_PERSON", "description is third person", rel, ln)
     if house:
+        # Both report either way: "the house rules were checked" has to be
+        # provable from the output the canon tells the agent to cite.
         if not desc.lower().startswith("use when"):
             a.gap("DESC_USEWHEN", "description must start with 'Use when …' (house rule)", rel, ln)
+        else:
+            a.ok("DESC_USEWHEN", "description opens with 'Use when …' (house rule)", rel, ln)
         if not re.search(r"[а-яё]", desc, re.I):
             a.gap("DESC_RU", "description carries no Russian trigger phrases (house rule)", rel, ln)
+        else:
+            a.ok("DESC_RU", "description carries Russian trigger phrases (house rule)", rel, ln)
+        if DESC_TARGET < len(desc) <= DESC_MAX:
+            a.gap("DESC_HEADROOM", "description is %d chars — inside the %d cap but past the "
+                  "%d working limit (house rule): leave room for the 'what this is NOT for' "
+                  "clause a near-miss neighbour will require"
+                  % (len(desc), DESC_MAX, DESC_TARGET), rel, ln)
+        elif len(desc) <= DESC_TARGET:
+            a.ok("DESC_HEADROOM", "description is %d/%d chars, inside the working limit"
+                 % (len(desc), DESC_TARGET), rel, ln)
 
 
 def _check_optional_fields(a, fm, lines, rel):
@@ -253,13 +274,18 @@ def _check_keys(a, fm, lines, rel):
 def _check_body_budget(a, body, rel):
     n_lines = body.count("\n") + 1
     est = int(len(body) / CHARS_PER_TOKEN)
+    # Both, not either: a body over the line budget still has to report its
+    # token count, or the second fix arrives only after the first one ships.
+    over = False
     if n_lines >= BODY_MAX_LINES:
         a.gap("BODY_LINES", "body is %d lines, the budget is < %d — move detail into "
               "references/" % (n_lines, BODY_MAX_LINES), rel)
-    elif est >= BODY_MAX_TOKENS:
+        over = True
+    if est >= BODY_MAX_TOKENS:
         a.gap("BODY_TOKENS", "body is ~%d tokens (%d chars / %s), the budget is < %d"
               % (est, len(body), CHARS_PER_TOKEN, BODY_MAX_TOKENS), rel)
-    else:
+        over = True
+    if not over:
         a.ok("BODY_BUDGET", "body is %d lines / ~%d tokens (budget %d / %d)"
              % (n_lines, est, BODY_MAX_LINES, BODY_MAX_TOKENS), rel)
 
@@ -295,21 +321,27 @@ def _check_bundle(a, skill_dir, skill_text, dir_name):
 
 
 def _check_links(a, skill_dir, skill_text, rel):
-    """A relative link that escapes the skill directory arrives broken everywhere."""
-    escaped = broken = False
-    for target in LINK_RE.findall(skill_text):
-        if target.startswith(("http://", "https://", "mailto:", "#")):
-            continue
-        if target.startswith("../") or "/../" in target:
-            a.gap("LINK_ESCAPE", "link %r escapes the skill directory — packagers ship "
-                  "that directory alone, so it arrives broken on every agent" % target, rel)
-            escaped = True
-            continue
-        path = os.path.normpath(os.path.join(skill_dir, target.split("#")[0]))
-        if not os.path.exists(path):
-            a.gap("LINK_BROKEN", "link %r does not resolve" % target, rel)
-            broken = True
-    if not escaped and not broken:
+    """A relative link that escapes the skill directory arrives broken everywhere.
+
+    Reported per line: the canon defines evidence as a `file:line`, so a finding
+    without one forces the agent to either drop the evidence or invent it.
+    """
+    bad = False
+    for i, line in enumerate(skill_text.split("\n"), start=1):
+        for target in LINK_RE.findall(line):
+            if target.startswith(("http://", "https://", "mailto:", "#")):
+                continue
+            if target.startswith("../") or "/../" in target:
+                a.gap("LINK_ESCAPE", "link %r escapes the skill directory — packagers "
+                      "ship that directory alone, so it arrives broken on every agent"
+                      % target, rel, i)
+                bad = True
+                continue
+            path = os.path.normpath(os.path.join(skill_dir, target.split("#")[0]))
+            if not os.path.exists(path):
+                a.gap("LINK_BROKEN", "link %r does not resolve" % target, rel, i)
+                bad = True
+    if not bad:
         a.ok("LINK_INTEGRITY", "every relative link resolves and stays inside the skill", rel)
 
 
@@ -335,8 +367,11 @@ def _check_prose(a, body, rel):
             a.gap("TIME_BRANCH", "time-branching instruction (%r) — it is wrong the day "
                   "it ships; put superseded material under '## Old patterns'"
                   % raw.strip()[:60], rel, i)
-    # a pointer at a directory rather than a file with a load condition
-    for i, line in enumerate(body.split("\n"), start=1):
+    # A pointer at a directory rather than a file with a load condition. Quoted
+    # spans are blanked here too: a canon that forbids "see references/" has to
+    # be able to quote the phrase it forbids.
+    for i, raw in enumerate(body.split("\n"), start=1):
+        line = _strip_quoted(raw)
         if re.search(r"\b(?:see|read)\s+`?(?:references|scripts|assets)/`?(?![\w.-])", line, re.I):
             a.gap("REF_NO_TRIGGER", "points at a directory instead of a file with a "
                   "stated load condition — 'read X when Y' beats 'see references/'", rel, i)