@ssheleg/make-skill 0.10.0 → 0.11.0

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

@@ -171,7 +171,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 +214,16 @@ 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)
 
 
 def _check_optional_fields(a, fm, lines, rel):
@@ -253,13 +262,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 +309,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 +355,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)