@ssheleg/make-skill 0.28.0 → 0.29.1

package/CHANGELOG.md

@@ -1,3 +1,43 @@
+## v0.29.1 — indented plain descriptions are measured correctly
+
+The auditor now accepts a plain YAML description whose text begins on the
+next indented line. It folds continuation lines, preserves paragraph breaks,
+and respects comment boundaries instead of reporting a valid description as
+missing. Bare typed values remain subject to the field's string requirement.
+
+Unsupported forms in that path produce `FM_SUBSET_UNSUPPORTED`; field checks
+remain unmeasured instead of making a missing-value claim. The parser stays
+dependency-free, with an installed full YAML parser used only as an optional
+oracle. The regression covers valid strings, actual missing/invalid values,
+length limits, metadata maps, comments and the no-PyYAML path.
+
+## v0.29.0 — the standard now reads a hook key the host ignores
+
+Claude Code 2.1.270 began printing `hooks.json: unknown key "if" in
+hooks.PreToolUse[1] ignored` at every session start. The key had been there since
+agent-sync 0.1.0, and the same shape sat in the hooks template `task-pipeline`
+exports into consumer projects — where the documentation gate then ran on **every**
+Bash call rather than on commits. Nothing caught it: not nine member validators, not
+this auditor, and not `claude plugin validate --strict`, which accepts the file.
+
+- **`HOOKS_SCHEMA`** reads the plugin's `hooks/hooks.json` from a skill at
+  `<plugin>/skills/<name>` and refuses any key outside the set its level accepts —
+  a matcher group takes `matcher` + `hooks`; a `command` handler takes `type`,
+  `command`, `args`, `if`, `shell`, `timeout`, `statusMessage`, `once`, `async`,
+  `asyncRewake` and three `@internal` keys. Both sets are read out of the 2.1.270
+  binary's schema rather than from prose. A manifest that does not parse is a GAP
+  (the host then loads no hooks at all); a plugin with no manifest passes and says
+  so; a `prompt`/`agent`/`http`/`mcp_tool` handler is **declared unchecked**,
+  because only the command handler's key set was measured.
+- **`BUNDLE_NESTED` stops reporting `__pycache__`.** A byte-compile cache appears
+  the moment a test imports a shipped module; it is gitignored and npm-excluded in
+  every member, and three of them were carrying the gap for a directory that never
+  ships.
+- `references/host-capabilities.md` states both key sets, where `if` lives, the
+  loader's exact warning, and that `validate --strict` is not the gate for this.
+
+Every shipped skill in the family passes: 28 of 28 at `0 GAP`, now `19 PASS`.
+
 ## v0.28.0 — the house audit measures the token budget instead of estimating it
 
 Sherlock external-v3 (13 findings) plus the enterprise handoff (PR #18) and the

package/package.json

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

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.28.0",
+  "version": "0.29.1",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -5,7 +5,7 @@ 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.28.0"
+  version: "0.29.1"
   homepage: https://github.com/ssheleg/make-skill
 ---
 

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

@@ -83,7 +83,28 @@ 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 *)"`.
+`if`, a permission rule: `"if": "Bash(git commit *)"` — **inside the handler
+object**, beside `type` and `command`.
+
+**Two key sets, and putting a key in the wrong one is silent.** Read out of the
+2.1.270 binary's schema: a matcher group takes `matcher` and `hooks`, nothing
+else; a `command` handler takes `type`, `command`, `args`, `if`, `shell`,
+`timeout`, `statusMessage`, `once`, `async`, `asyncRewake` (plus three
+`@internal` keys). Anything outside its set is **ignored** — the hook still runs,
+with the key doing nothing. Before 2.1.270 nothing said so at all; from it the
+loader prints once per session:
+
+```
+Plugin <name>: hooks.json: unknown key "if" in hooks.PreToolUse[1] ignored
+```
+
+`claude plugin validate --strict` accepts the file either way, so a skill audit
+is the only gate that catches this before a session starts — `HOOKS_SCHEMA` in
+`scripts/audit_skill.py` reads both sets. The family paid for that check: `if`
+sat beside `matcher` in `agent-sync` from 0.1.0 to 1.20.0 (harmless — its guard
+narrowed to a commit with its own parser), and in the hooks template
+`task-pipeline` tells projects to paste into `settings.json`, where the
+documentation gate then ran on **every** Bash call instead of on commits.
 
 **Exit codes are the contract:**
 
@@ -245,6 +266,8 @@ what the agent reads at the exact moment something is missing.
 - [ ] 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`
+- [ ] Every key is in the set its level accepts — a filter goes on the handler,
+      never beside `matcher`, where the host ignores it without failing
 - [ ] Hook scripts are executable, have a shebang, and need no `jq`
 - [ ] No command named after a skill — or the collision is on a recorded, dated
       exception list (see *Commands*); every `argument-hint` quoted

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

@@ -247,6 +247,26 @@ TIME_BRANCH_RE = re.compile(
     r"(?:january|february|march|april|may|june|july|august|september|october|"
     r"november|december|\d{4})\b", re.I)
 BUNDLE_DIRS = ("references", "scripts", "assets")
+# A byte-compile cache is not a bundled directory: `__pycache__` appears the moment a
+# test imports a shipped module, is gitignored and npm-excluded in every member, and
+# three of them were reporting BUNDLE_NESTED for a directory that never ships.
+BUNDLE_IGNORE = ("__pycache__",)
+
+# Claude Code's hooks schema, read out of the 2.1.270 binary rather than from the
+# documentation: `Rt()` is the matcher GROUP and `Td()` the handler union. A key outside
+# these sets is IGNORED — silently before 2.1.270, and from it announced once per session
+# as `Plugin <name>: hooks.json: unknown key "<k>" in hooks.<Event>[<i>] ignored`. It is
+# not a syntax error, `claude plugin validate --strict` passes the file, and the hook goes
+# on running with the filter absent. agent-sync shipped `"if"` beside `"matcher"` from
+# 0.1.0 to 1.20.0 and task-pipeline exported the same shape in the template it tells
+# projects to paste into `settings.json`, where the gate then ran on every Bash call.
+HOOK_GROUP_KEYS = {"matcher", "hooks"}
+# The `command` handler. `if` is HERE — beside `type` and `command`, never beside
+# `matcher`. The last three are marked `@internal` in the schema and are accepted.
+HOOK_COMMAND_KEYS = {
+    "type", "command", "args", "if", "shell", "timeout", "statusMessage", "once",
+    "async", "asyncRewake", "rewakeMessage", "rewakeSummary", "cloud",
+}
 
 # A file in a publishable payload whose name reads as a credential. Fixtures and
 # test data are the common carriers; the auditor names it rather than shipping it.
@@ -283,7 +303,8 @@ def parse_frontmatter(text):
     """A STRICT stdlib precheck of an explicitly bounded YAML subset — NOT full
     YAML, and it does not pretend to be (FIX-MS-02.01).
 
-    The supported subset: top-level scalars (quoted or plain), block scalars
+    The supported subset: top-level scalars (quoted or plain, including a plain
+    value starting on the next indented line), block scalars
     (`>`/`|` and their chomping variants), inline flow sequences (`[a, b]`),
     and ONE nested map. Everything else is out of subset and must be caught,
     never waved through — a precheck that silently accepts what the real
@@ -305,12 +326,34 @@ def parse_frontmatter(text):
     for a skill the Skills API rejects on upload (2026-08-16, B-63).
     """
     parse_frontmatter.last_duplicates = []
+    parse_frontmatter.last_unsupported = {}
     data, lines, key, mode = {}, {}, None, None
     scalars = set()
     duplicates = []            # (scope, key) pairs seen more than once
     nested_seen = set()
+    blank_lines = 0
+    plain_closed = False
+
+    def plain_part(value):
+        # Only plain scalars: quotes and flow values use their existing path.
+        # A hash in a URL is data; whitespace followed by # starts a comment.
+        m = re.search(r"(?:^|\s)#", value)
+        return (value[:m.start()].rstrip(), True) if m else (value, False)
+
+    def unsupported(reason):
+        parse_frontmatter.last_unsupported[key] = reason
+        data[key] = None
+        scalars.discard(key)
+
     for i, raw in enumerate(text.split("\n"), start=2):  # +2: the opening '---'
         if not raw.strip():
+            if mode == "plain":
+                blank_lines += 1
+            continue
+        if raw.lstrip().startswith("#") and (
+                raw[0] not in " \t" or mode in (None, "pending", "plain", "map")):
+            if mode == "plain":
+                plain_closed = True
             continue
         if raw[0] not in " \t":
             m = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", raw)
@@ -322,10 +365,14 @@ def parse_frontmatter(text):
                 duplicates.append(("top", key))
             nested_seen = set()
             lines[key] = i
+            blank_lines, plain_closed = 0, False
+            # Delay the map/scalar decision: `description:` can introduce either.
+            if val.startswith("#"):
+                val = ""
             if val in (">", "|", ">-", "|-", ">+", "|+"):
                 data[key], mode = "", "block"
             elif val == "":
-                data[key], mode = {}, "map"
+                data[key], mode = None, "pending"
             else:
                 # Kept RAW here and finished at the end: a quoted scalar that
                 # spans lines carries its closing quote on the last one, so
@@ -333,10 +380,38 @@ def parse_frontmatter(text):
                 # buried in the middle of the folded value.
                 data[key], mode = val, "scalar"
                 scalars.add(key)
+                if val[0] not in "\"'[{":
+                    data[key], plain_closed = plain_part(val)
+                    mode = "plain"
+        elif mode == "pending":
+            value = raw.strip()
+            if re.match(r"^[A-Za-z0-9_-]+:(?:\s|$)", value):
+                data[key], mode = {}, "map"
+                m = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", value)
+                nested_seen.add(m.group(1))
+                data[key][m.group(1)] = _typed_scalar(m.group(2).strip())
+            elif value[0] in "&*!{[|>" or re.match(r"^[-?:](?:\s|$)", value):
+                unsupported("indented value uses a YAML form outside the plain-scalar subset")
+                mode = "unsupported"
+            else:
+                data[key], mode = value, "scalar"
+                scalars.add(key)
+                if value[0] not in "\"'":
+                    data[key], plain_closed = plain_part(value)
+                    mode = "plain"
         elif mode == "block":
             data[key] = (data[key] + " " + raw.strip()).strip()
         elif mode == "scalar":
             data[key] = (data[key] + " " + raw.strip()).strip()
+        elif mode == "plain":
+            value, closed = plain_part(raw.strip())
+            if plain_closed or re.search(r":(?:\s|$)", value):
+                unsupported("plain scalar continuation follows a comment or contains a mapping separator")
+                mode = "unsupported"
+            else:
+                separator = "\n" * blank_lines if blank_lines else " "
+                data[key] += separator + value
+                blank_lines, plain_closed = 0, closed
         elif mode == "map":
             m = re.match(r"^\s+([A-Za-z0-9_-]+):\s*(.*)$", raw)
             if m:
@@ -385,7 +460,7 @@ def _finish_scalar(v):
     if len(v) >= 2 and v[0] == "[" and v[-1] == "]":
         inner = v[1:-1].strip()
         return [] if not inner else [_unquote(p.strip()) for p in inner.split(",")]
-    return _unquote(v)
+    return _typed_scalar(v)
 
 
 def _unquote(v):
@@ -416,6 +491,7 @@ def audit(skill_dir, house=False):
               "the file, delimited by ---", rel, 1)
         return a
     fm, fm_lines = parse_frontmatter(m.group(1))
+    unsupported = dict(getattr(parse_frontmatter, "last_unsupported", {}))
     body = text[m.end():]
 
     dups = getattr(parse_frontmatter, "last_duplicates", [])
@@ -441,12 +517,20 @@ def audit(skill_dir, house=False):
         a.ok("FM_YAML_CONFORMANCE", "the subset parse matches the installed "
              "YAML parser", rel)
 
-    _check_name(a, fm, fm_lines, name_on_disk, rel)
-    _check_description(a, fm, fm_lines, rel, house)
-    _check_optional_fields(a, fm, fm_lines, rel)
+    for key, reason in unsupported.items():
+        a.gap("FM_SUBSET_UNSUPPORTED", "%s: %s; field checks are unmeasured, "
+              "not evidence of a missing or invalid value" % (key, reason),
+              rel, fm_lines.get(key))
+    if "name" not in unsupported:
+        _check_name(a, fm, fm_lines, name_on_disk, rel)
+    if "description" not in unsupported:
+        _check_description(a, fm, fm_lines, rel, house)
+    measured = {k: v for k, v in fm.items() if k not in unsupported}
+    _check_optional_fields(a, measured, fm_lines, rel)
     _check_keys(a, fm, fm_lines, rel)
     _check_body_budget(a, body, rel, house)
     _check_bundle(a, skill_dir, text, name_on_disk)
+    _check_plugin_hooks(a, skill_dir)
     _check_links(a, skill_dir, text, rel)
     _check_distribution(a, skill_dir, name_on_disk)
     _check_prose(a, body, rel)
@@ -741,6 +825,8 @@ def _check_bundle(a, skill_dir, skill_text, dir_name):
         for entry in sorted(os.listdir(d)):
             full = os.path.join(d, entry)
             rel = os.path.join(dir_name, sub, entry)
+            if entry in BUNDLE_IGNORE:
+                continue
             if os.path.isdir(full):
                 a.gap("BUNDLE_NESTED", "%s/%s/ is nested — keep bundled files one level "
                       "deep, or the agent previews them instead of reading them"
@@ -762,6 +848,84 @@ def _check_bundle(a, skill_dir, skill_text, dir_name):
         a.ok("BUNDLE_LAYOUT", "bundled directories present and checked")
 
 
+def _check_plugin_hooks(a, skill_dir):
+    """The plugin's `hooks.json` carries only keys the host evaluates.
+
+    A skill inside a Claude Code plugin sits at `<plugin>/skills/<name>`, so the hooks
+    manifest is two levels up. This runs once per skill, which means a defective manifest
+    is reported once per skill of that plugin — a repetition, never a miss.
+
+    Reported as a GAP rather than a note because the failure is silent in both
+    directions: the key does nothing, and nothing said so for six weeks across two
+    repositories. `claude plugin validate --strict` accepts the file, so a skill audit is
+    the only gate this class can be caught by before a session start.
+    """
+    d = os.path.abspath(skill_dir.rstrip("/"))
+    parent = os.path.dirname(d)
+    if os.path.basename(parent) != "skills":
+        a.ok("HOOKS_SCHEMA", "not a plugin skill layout (<plugin>/skills/<name>) — no "
+             "hooks manifest to read from here")
+        return
+    plugin = os.path.dirname(parent)
+    path = os.path.join(plugin, "hooks", "hooks.json")
+    rel = os.path.join(os.path.basename(plugin), "hooks", "hooks.json")
+    if not os.path.isfile(path):
+        a.ok("HOOKS_SCHEMA", "the plugin ships no hooks/hooks.json — nothing to read", rel)
+        return
+    try:
+        data = json.load(open(path, encoding="utf-8"))
+    except Exception as e:
+        a.gap("HOOKS_SCHEMA", "hooks.json does not parse (%s) — Claude Code loads no "
+              "hooks at all from a manifest it cannot read" % e, rel)
+        return
+    events = data.get("hooks")
+    if not isinstance(events, dict):
+        a.gap("HOOKS_SCHEMA", "hooks.json has no `hooks` object — the manifest declares "
+              "nothing the host can run", rel)
+        return
+    bad = []
+    unchecked = set()
+    for event, groups in sorted(events.items()):
+        if not isinstance(groups, list):
+            bad.append("hooks.%s is not a list of matcher groups" % event)
+            continue
+        for i, group in enumerate(groups):
+            if not isinstance(group, dict):
+                bad.append("hooks.%s[%d] is not an object" % (event, i))
+                continue
+            for k in sorted(set(group) - HOOK_GROUP_KEYS):
+                bad.append('hooks.%s[%d]: %r sits beside `matcher`, where a matcher group '
+                           'takes only matcher+hooks — the host ignores it (a filter '
+                           'belongs inside the handler)' % (event, i, k))
+            handlers = group.get("hooks")
+            if not isinstance(handlers, list):
+                bad.append("hooks.%s[%d].hooks is not a list of handlers" % (event, i))
+                continue
+            for j, h in enumerate(handlers):
+                if not isinstance(h, dict):
+                    bad.append("hooks.%s[%d].hooks[%d] is not an object" % (event, i, j))
+                    continue
+                if h.get("type") != "command":
+                    unchecked.add(str(h.get("type")))
+                    continue
+                for k in sorted(set(h) - HOOK_COMMAND_KEYS):
+                    bad.append("hooks.%s[%d].hooks[%d]: %r is not a key the command-hook "
+                               "schema knows — the host ignores it" % (event, i, j, k))
+    for msg in bad:
+        a.gap("HOOKS_SCHEMA", msg, rel)
+    if not bad:
+        note = ""
+        if unchecked:
+            # Say what was NOT read. The command handler's key set was measured; the
+            # prompt/agent/http/mcp_tool handlers were not, and claiming them clean would
+            # be a verdict about something this check never looked at.
+            note = " (handler type(s) %s not checked — only the command handler's key "
+            note %= ", ".join(sorted(unchecked))
+            note += "set is measured here)"
+        a.ok("HOOKS_SCHEMA", "every hooks.json key is one Claude Code evaluates%s" % note,
+             rel)
+
+
 def _check_links(a, skill_dir, skill_text, rel):
     """A relative link that escapes the skill directory arrives broken everywhere.