@ssheleg/make-skill 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## v0.13.0
+
+### Fixed
+
+- **`BUNDLE_UNREACHABLE` read reachability as one hop and called 29 correctly-shipped
+  contracts dead weight.** The check asked whether `references/foo.md` appears as a
+  substring of `SKILL.md`. But a packager ships a skill's directory alone, so a
+  reference that links a sibling contract makes that sibling *required* — omit it and
+  the first arrives with a dangling link. Reachability is therefore the transitive
+  closure, which is exactly what `super-ux`'s own sync script computes, and the check
+  disagreed with the mechanism it was auditing.
+
+  Measured on `super-ux`: 29 → 0, with every other repository in the family byte-identical
+  before and after. Probed both ways — a planted orphan is still flagged, and a file
+  reachable only through another reference is not. The failing example was
+  `ux-flows/references/figma-structure.md`: no direct link from `SKILL.md`, linked by
+  `figma-integration.md`, `best-practices.md` and `system-map.md`, all three of which
+  `SKILL.md` links directly.
+
+- **The false positive was also masking real findings.** An entry flagged unreachable
+  `continue`d past the `REF_NO_TOC` check, so a 312-line reference with no `## Contents`
+  was invisible behind a gap that should never have fired. Fixing the reachability
+  surfaced four of those — the correct behaviour, and the reason a false positive is not
+  merely noise.
+
+**Minor rather than patch**: for a tool whose output *is* its product, changing what it
+reports changes what everyone downstream sees, and one of those changes is new findings
+appearing on repositories that were green.
+
 ## v0.12.0
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way — 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.12.0",
+  "version": "0.13.0",
   "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.12.0"
+  version: "0.13.0"
   homepage: https://github.com/ssheleg/make-skill
 ---
 

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

@@ -290,8 +290,53 @@ def _check_body_budget(a, body, rel):
              % (n_lines, est, BODY_MAX_LINES, BODY_MAX_TOKENS), rel)
 
 
+def _bundle_closure(skill_dir, skill_text):
+    """Bundled files reachable from SKILL.md, following links between them.
+
+    Reachability is transitive, not one hop. A reference that links a sibling contract
+    makes that sibling reachable, and shipping the first without the second is what
+    leaves a dangling link on the target agent — so a packager that computes what a
+    skill needs has to take the closure, and the check has to agree with it. Measured
+    against super-ux, where the one-hop reading called 29 transitively-linked contracts
+    dead weight.
+    """
+    available = {}
+    for sub in BUNDLE_DIRS:
+        d = os.path.join(skill_dir, sub)
+        if not os.path.isdir(d):
+            continue
+        for entry in os.listdir(d):
+            if os.path.isfile(os.path.join(d, entry)):
+                available["%s/%s" % (sub, entry)] = os.path.join(d, entry)
+
+    seen = set()
+    stack = [key for key in available if key in skill_text]
+    while stack:
+        key = stack.pop()
+        if key in seen:
+            continue
+        seen.add(key)
+        if not key.endswith(".md"):
+            continue
+        sub = key.split("/", 1)[0]
+        try:
+            txt = open(available[key], encoding="utf-8").read()
+        except (OSError, UnicodeDecodeError):
+            continue
+        for target in LINK_RE.findall(txt):
+            t = target.split("#", 1)[0].strip().lstrip("./")
+            if not t or "://" in t:
+                continue
+            # a bare name inside references/ means a sibling of that same directory
+            cand = t if "/" in t else "%s/%s" % (sub, t)
+            if cand in available and cand not in seen:
+                stack.append(cand)
+    return seen
+
+
 def _check_bundle(a, skill_dir, skill_text, dir_name):
     """references/ scripts/ assets/: one level deep, reachable, navigable."""
+    reachable = _bundle_closure(skill_dir, skill_text)
     for sub in BUNDLE_DIRS:
         d = os.path.join(skill_dir, sub)
         if not os.path.isdir(d):
@@ -304,10 +349,10 @@ def _check_bundle(a, skill_dir, skill_text, dir_name):
                       "deep, or the agent previews them instead of reading them"
                       % (sub, entry), rel)
                 continue
-            if "%s/%s" % (sub, entry) not in skill_text:
-                a.gap("BUNDLE_UNREACHABLE", "%s/%s is never referenced from SKILL.md — "
-                      "an unreachable file is dead weight the agent never opens"
-                      % (sub, entry), rel)
+            if "%s/%s" % (sub, entry) not in reachable:
+                a.gap("BUNDLE_UNREACHABLE", "%s/%s is not reachable from SKILL.md, "
+                      "directly or through another bundled file — an unreachable file "
+                      "is dead weight the agent never opens" % (sub, entry), rel)
                 continue
             if entry.endswith(".md"):
                 txt = open(full, encoding="utf-8").read()