@ssheleg/make-skill 0.29.0 → 0.29.2

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## v0.29.2 — portable procedures, host-specific capabilities
+
+Authoring guidance now distinguishes the skills-CLI payload from native plugin
+channels. It detects hooks, delegation, commands and MCP per host instead of
+claiming every non-Claude runtime lacks them. Network requirements describe the
+sandbox capability, and examples preserve an inline fallback.
+
+The Claude validation guidance records a 2.1.296 positive/negative probe: missing
+skill descriptions fail strict validation, while an unknown skill key still
+passes. Tool grants and plugin text substitution are separated from restrictions
+and exported shell variables. Native Codex packaging and optional skill metadata
+are linked to current primary documentation.
+
+## 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

package/README.md

@@ -104,15 +104,15 @@ both manifests, in CI as its own job. That check is what caught this repo's own
 `marketplace.json` shipping `homepage` and `repository` at a level where Claude
 Code ignores them.
 
-**The Claude Code power set — with a fallback for everywhere else.** The skill
+**Host capabilities — detect them and provide a fallback.** The skill
 ships what it teaches: a `PostToolUse` **hook** that audits a `SKILL.md` the
 moment you save one (and exits silently for every other write, in every other
 project), a **subagent** for auditing a repo full of skills without crowding the
 main thread, a `/skill-audit` **command**, and a stdlib **script** that does the
-mechanical half of an audit deterministically. Hooks, subagents and commands
-exist only inside Claude Code — so the canon makes the fallback a rule: **every
+mechanical half of an audit deterministically. Those bundled components use
+Claude Code schemas; other hosts need their own activation checks. **Every
 host capability is an accelerator with a written fallback**, for three named
-cases (not Claude Code, recommended plugin absent, tool or MCP server absent).
+cases (required host capability absent, recommended plugin absent, tool or MCP server absent).
 A fallback you know but did not write is not a fallback.
 
 **Evaluations, not vibes.** The canon requires every skill to carry at least

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.29.0",
+  "version": "0.29.2",
   "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.29.0",
+  "version": "0.29.2",
   "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.29.0"
+  version: "0.29.2"
   homepage: https://github.com/ssheleg/make-skill
 ---
 
@@ -75,8 +75,8 @@ differences and the checklist: `references/agent-skills-spec.md`.
   plugin listing nor an installed skill, and nothing errors, so the gap stays
   open (all six repos here, 2026-07-30).
 - **Host extensions are legal, never load-bearing.** Claude Code reads a further
-  host-only set (`references/claude-code-plugin.md`); other agents ignore it, so
-  a skill DEPENDING on one is broken everywhere else. Outside spec ∪ host = typo.
+  host-specific set (`references/claude-code-plugin.md`). Detect host support;
+  keep a portable fallback.
 - Body **< 500 lines and < 5000 tokens**, and hold **5% headroom** — a body at
   99% of budget turns the next correction into a fight with the validator.
   Heavier material goes to `references/`, `scripts/`, `assets/` INSIDE the skill
@@ -86,10 +86,10 @@ differences and the checklist: `references/agent-skills-spec.md`.
 - Gotchas stay in `SKILL.md`: the agent can't know to open a file about a trap
   it doesn't know exists.
 - **Write for the weakest surface you claim** (`references/surfaces.md`): the
-  Claude API container has NO network and NO package install, claude.ai varies,
-  only Claude Code has both. A script that `pip install`s or curls is a Claude
-  Code skill — say so in `compatibility` or drop it. Nothing syncs between
-  surfaces; git is the source of truth.
+  Claude API container has NO network and NO package install, claude.ai varies.
+  Other coding hosts follow their sandbox policy. Declare network/interpreter
+  requirements and an offline/manual fallback. Deploy per channel; see
+  `references/surfaces.md` for account-sync exceptions.
 
 House additions on top of the spec:
 
@@ -179,8 +179,8 @@ regardless:
 - **Version sync (hard rule):** marketplace.json, plugin.json, package.json and
   the top CHANGELOG entry carry the SAME semver, bumped together (+ a 5th point
   if `SKILL.md` carries `metadata.version`).
-- **Both `--strict` runs green, in CI, as their own job** — they read MANIFESTS
-  only, so front-matter rules live in your own `test/validate.py`, which needs a
+- **Both `--strict` runs green, in CI, as their own job** — coverage varies by CLI version; keep
+  front-matter rules in your own `test/validate.py`, which needs a
   negative self-test: a validator that can't fail is decoration. Ship `$schema`
   and `displayName` in `plugin.json` AND the marketplace ENTRY (the marketplace
   root takes neither).

package/plugins/make-skill/skills/make-skill/references/agent-skills-spec.md

@@ -143,13 +143,24 @@ Rules:
 (Codex) provide subagents and MCP natively. DETECT the capability; do not
 assume its absence. Presence is per host AND per version.
 
-| Capability | Claude Code | Codex | Cursor | skills CLI / API | Detect by |
-|---|---|---|---|---|---|
-| Hooks | yes | no | no | no | host docs / config |
-| Subagents | yes | **yes (native)** | no | no | runtime probe |
-| MCP servers | yes | **yes (native)** | varies | no | runtime probe |
-| `/commands` | yes | no | no | no | host docs |
-| Plugin path vars | yes | no | no | no | env presence |
+| Capability | Portable contract | Host-specific verification |
+|---|---|---|
+| Hooks | no portable skill hook lifecycle | inspect the host's supported events, payloads and installation scope |
+| Subagents | procedure remains executable inline | discover the actual delegation tool; verify agent definition format separately |
+| MCP servers | declare dependency and missing-server fallback | discover authenticated tools; do not hardcode vendor tool names |
+| Commands | natural-language or explicit skill invocation remains possible | verify command registration, namespace and argument substitution |
+| Plugin paths | resolve bundled files relative to the loaded skill directory | distinguish Markdown substitution from exported shell variables |
+
+Current examples, checked 2026-10-09: [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
+and [hooks](https://learn.chatgpt.com/docs/hooks) are real capabilities. Its
+[plugin packaging](https://developers.openai.com/plugins/build/plugins) supports
+portable root manifests and Codex compatibility layouts; public-directory and
+manual-install hook eligibility differ. [Local skills](https://learn.chatgpt.com/docs/build-skills)
+can have `agents/openai.yaml` for optional UI, invocation and tool dependencies.
+Those files do not replace the portable skill or grant unavailable permissions.
+
+The skills CLI installs files; an API/container surface has its own runtime.
+Neither belongs in a single yes/no column with an interactive coding host.
 
 And every NORM this skill enforces carries its **owner** (spec = the Agent
 Skills standard, host = a runtime's own rule, house = this family), whether it

package/plugins/make-skill/skills/make-skill/references/claude-code-plugin.md

@@ -18,9 +18,9 @@ trusting a version-gated field in a new quarter.*
 
 The [Agent Skills spec](https://agentskills.io/specification) (see
 `references/agent-skills-spec.md`) is the portable floor. **This file is the
-host layer on top of it**: everything here is Claude-Code-specific and is
-ignored by other agents — so nothing here may be load-bearing for a skill that
-must also run on Cursor, Codex, or the skills CLI.
+host layer on top of it**. Other hosts may support selected compatibility fields,
+but cannot be assumed to implement this whole contract. Keep a portable skill
+procedure and verify extensions separately for each claimed host and version.
 
 ## Contents
 
@@ -53,12 +53,10 @@ Both must exit 0. Rules that decide the outcome:
 - Wrong **types** always fail (`keywords` as a string, not an array).
 - It runs offline and needs no auth, so it belongs in CI:
   `npm i -g @anthropic-ai/claude-code && claude plugin validate … --strict`.
-- **It validates the MANIFEST, whatever the docs promise.** The troubleshooting
-  table says the command checks "`plugin.json`, skill/agent/command frontmatter,
-  and `hooks/hooks.json`"; on 2.1.212 a `SKILL.md` carrying an invented
-  front-matter key passed `--strict` untouched, and the output names only the
-  manifest it read. Keep front-matter rules in your own validator — this gate
-  does not cover them.
+- **Coverage is versioned and partial.** The older 2.1.212 probe only inspected
+  manifests. On 2.1.296, a missing skill description fails `--strict`, while an
+  invented front-matter key still passes (probe dated 2026-10-09). Keep the house
+  validator; manifest success is neither complete format nor runtime acceptance.
 
 ## `plugin.json` — `.claude-plugin/plugin.json`
 
@@ -206,8 +204,11 @@ Portable floor (`name`, `description`, `license`, `compatibility`, `metadata`,
 `allowed-tools`) is in `references/agent-skills-spec.md`. **`allowed-tools` is
 looser here than in the spec**: Claude Code takes a space- OR comma-separated
 string OR a YAML list, the spec takes only the space-separated string. Write the
-spec form — a list works here and breaks everywhere else. Claude Code also
-reads:
+spec form for portable authoring; list acceptance elsewhere is host-specific.
+`allowed-tools` pre-approves named tools for the invocation turn; it does not
+remove other tools and the grant clears on the next user message. Managed policy
+may ignore these grants. This is host behavior, never permission supplied by a
+portable skill. Claude Code also reads:
 
 | Field | Effect |
 |---|---|
@@ -297,18 +298,15 @@ They substitute in skill/agent content, hook and monitor commands, MCP
 `command`/`args`/`env`/`workspaceFolder`. In shell-form commands, quote them:
 `"${CLAUDE_PLUGIN_ROOT}"/scripts/x.sh`.
 
-**They are NOT exported to the Bash tool.** Substitution into text and export
-into a process are different things: a hook script sees `CLAUDE_PLUGIN_ROOT` in
-its environment, a `Bash` tool call does not (measured empty on 2.1.220). So a
-skill that *prints* the variable gets a real path, and a skill that tells the
-agent to *run* a command containing it gets `/skills/...` and a missing-file
-error. Put runnable scripts in the plugin's `bin/`, which lands on the Bash
-tool's PATH, and call them by name — `references/host-capabilities.md` →
-*Scripts*.
+**They are NOT exported to the Bash tool.** A command in loaded Markdown can
+contain a substituted absolute path and run correctly. A raw shell command that
+expects the variable in its process environment cannot: the older 2.1.220 probe
+measured that environment case. Use quoted Markdown substitution or a plugin
+`bin/` wrapper; other hosts resolve bundled files relative to the loaded skill.
+See `references/host-capabilities.md` → *Scripts*.
 
-**Portability:** all four are Claude Code inventions. A skill that must also run
-on other agents references bundled files by **relative path** and treats the
-variables as an optimization, not the contract.
+**Portability:** verify each host's substitutions. A skill-relative path is the
+portable contract; Claude's variables and plugin PATH are optional conveniences.
 
 ## Caching, symlinks, path traversal
 
@@ -320,8 +318,8 @@ orphaned versions are cleaned up ~14 days later. Consequences:
 - Symlinks inside the plugin dir are preserved; symlinks to elsewhere in the
   same marketplace are **dereferenced** (content copied); symlinks outside the
   marketplace are skipped. This is why a meta-plugin can link sibling skills —
-  and why the same trick still breaks on non-Claude agents, which install only
-  the skill folder.
+  and why the same trick still breaks in the skills-CLI channel, which installs
+  only the skill folder. Test native plugin channels separately.
 
 ## Skills-directory plugins
 

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

@@ -83,10 +83,12 @@ 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`).
+**What travels where.** The skills-CLI channel copies `skills/<skill>/`, so
+required scripts, skeletons and procedures must stay inside that directory.
+Native plugin channels can carry additional components, including in Codex; their
+schemas and activation differ. Never infer hook, agent or command registration
+from a skill-only install. Each component needs a fallback and host readback
+(`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
@@ -101,8 +103,8 @@ names: `references/claude-code-plugin.md`):
   `displayName` in both, keep component paths `./`-relative. Unrecognized fields
   are warnings the runtime tolerates and only `--strict` shows — that is how
   `homepage`/`repository`, plugin-ENTRY fields, sat at the marketplace root of
-  this repo unnoticed. It reads the MANIFEST only: front-matter rules stay in
-  your own validator, whatever the troubleshooting table promises.
+  this repo unnoticed. Recent versions also check selected skill metadata;
+  retain the house validator and negative probes because coverage is not complete.
 - **`claude plugin details <name>@<marketplace>`** — the only view of what Claude
   Code *thinks* the plugin contains and what it costs every session. Catches a
   component listed twice and a description worth trimming.
@@ -253,8 +255,9 @@ The canon, for every bin installer that targets `~/.claude/skills/`:
 - **Absence fails open; corruption never crashes.** A missing or unparsable
   `installed_plugins.json` reads as "no plugin" — the fresh HOME is the common case,
   and an installer that dies on a parse error refuses the machines that need it most.
-- **Only Claude Code has plugins.** The check gates the `~/.claude` write alone;
-  installs into other agents' skill directories are untouched by it.
+- **This guard covers the Claude channel.** It gates the `~/.claude` write alone.
+  Other hosts can have native plugins too; their provider resolution and lifecycle
+  need separate checks. This guard cannot establish their absence or precedence.
 - **CI runs the plugin-present case, not only a fresh HOME.** A fake HOME whose
   `installed_plugins.json` declares the plugin, asserting all three at once: the
   non-zero exit, the remedy in the output, and that nothing was written — plus the

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

@@ -7,7 +7,9 @@ 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.
+for the manifest side. Portability and path-substitution corrections checked
+2026-10-09 against the linked current docs; the older event examples are versioned
+examples, not a promise that another runtime accepts their payloads.
 
 ## Contents
 
@@ -24,9 +26,10 @@ for the manifest side.
 
 ## 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:
+The concrete schemas below describe Claude Code. Other coding hosts also provide
+hooks, subagents, commands or MCP, with different contracts and versions. Detect
+the actual capability and delivery channel; the skills CLI is an installer, not a
+runtime. A directory copied successfully does not register a hook or agent. 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.**
@@ -48,8 +51,10 @@ but did not write is not a fallback.
 | `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.
+The table uses Claude Code component names and cost estimates. Do not apply them
+as other hosts' schemas or token measurements. A skill-directory install carries
+its own scripts and references; native plugin channels may carry more components.
+Verify each advertised component in the receiving host before claiming support.
 
 ## Hooks — events, handlers, matchers, exit codes
 
@@ -154,8 +159,10 @@ an audit across twenty skills, a survey, a long verification — because its out
 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.
+Fallback: if this runtime exposes no suitable delegation tool, run the same
+procedure inline and report that self-review is weaker than independent review.
+If delegation exists, use its native contract; a Claude `agents/*.md` definition
+is not evidence that another host registered that agent.
 
 ## Commands
 
@@ -179,19 +186,21 @@ body receives `$ARGUMENTS`. Two rules cost a debugging round each:
   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.
+Fallback: if this host has no matching command registration, select the skill
+through its description or explicit path and follow its procedure. Do not assume
+a Claude command file, slash spelling or argument substitution works elsewhere.
 
 ## Scripts
 
-The one accelerator that travels. Keep it inside the skill directory
+The portable payload. Keep it inside the skill directory
 (`scripts/`), stdlib-only, and invoke it by a path the agent can actually
 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:
+**Distinguish text substitution from a shell environment.** Claude Code replaces
+`${CLAUDE_PLUGIN_ROOT}` in loaded Markdown; it does not export that variable to
+commands the Bash tool runs. Current plugin docs also say monitor commands receive
+substitution but no exported variables. The older direct-shell probe below
+(Claude Code 2.1.220) demonstrates the environment case, not failed substitution:
 
 ```bash
 $ echo "[${CLAUDE_PLUGIN_ROOT}]"
@@ -238,7 +247,7 @@ silently. Declare it in frontmatter `compatibility`, and write the branch:
 
 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.
+that enforcement outside this plugin channel must be verified separately.
 
 ## The three degradation cases, written out
 
@@ -247,9 +256,9 @@ 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.
+- **Required host capability unavailable** (hook, delegation or command): run
+  <procedure> inline and state the missing enforcement or independence. Detect
+  actual tools first; bundled scripts still need their declared interpreter.
 - **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
@@ -273,6 +282,6 @@ what the agent reads at the exact moment something is missing.
       exception list (see *Commands*); 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
+- [ ] Runnable paths use loaded-Markdown substitution, a `bin/` wrapper, or a
+      resolved skill-relative path; never depend on plugin variables in raw Bash env
 - [ ] MCP and sibling-skill dependencies declared in `compatibility` with a branch

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

@@ -125,7 +125,7 @@ Report the table before changing anything, then fix.
 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
+    (required host capability absent / 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 (a collision on
     the recorded, dated exception list in `references/host-capabilities.md` —

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

@@ -13,7 +13,7 @@ limits before locking a contract.
 ## Contents
 
 - The surface matrix — one table that decides portability
-- Nothing syncs — each surface is a separate deployment
+- Deploy per channel; account sync is a specific exception
 - Runtime constraints authors get wrong
 - Skills API — upload, version, attach
 - claude.ai
@@ -41,13 +41,16 @@ and pull from GitHub. Both are true per-tenant, which means neither is something
 to build on — treat claude.ai as "network may be off" and the skill still has to
 work.
 
-## Nothing syncs — each surface is a separate deployment
+## Deploy per channel; account sync is a specific exception
 
-A skill uploaded to the API is not on claude.ai and not in Claude Code, in any
-direction. There is no sync mechanism and none is planned in the docs. Keep the
-skill directory in git as the single source of truth and treat every surface as a
-publish target — which is exactly what the distribution matrix in
-`references/distribution.md` automates for the filesystem-based agents.
+API uploads and filesystem/plugin distributions remain separate deployment
+channels. Keep versioned source in Git and verify each target. Current
+[Claude Code documentation](https://code.claude.com/docs/en/skills#skills-synced-from-claudeai)
+(read 2026-10-09) documents claude.ai account skills syncing into terminal sessions
+from v2.1.273. It requires the supported account sign-in and policy; API-key,
+bare/safe-mode and managed restrictions can prevent it. This is download-only:
+local edits under `~/.claude/skills/synced/` are not uploaded and may be overwritten.
+Do not infer sync to other coding hosts or overwrite the account-managed cache.
 
 ## Runtime constraints authors get wrong
 
@@ -58,8 +61,8 @@ Written once for the surface you happen to use, a skill silently fails elsewhere
   [code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)
   list) or state the dependency in `compatibility` and give a fallback path.
 - **`curl`/`requests`/any fetch inside a script** — no network on the API, maybe
-  none on claude.ai. A skill whose only path to data is an HTTP call is a Claude
-  Code skill; say so in `compatibility`.
+  none on claude.ai. Other coding agents can allow network access under their own
+  sandbox policy. Declare the capability, not a single vendor, in `compatibility`.
 - **Global installs** (`npm i -g`, `pip install --user`) — discouraged even where
   they work: the skill is a guest on the user's machine.
 - **Absolute machine paths** (`/Users/you/...`) — nothing outside the skill

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

@@ -303,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
@@ -325,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)
@@ -342,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
@@ -353,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:
@@ -405,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):
@@ -436,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", [])
@@ -461,9 +517,16 @@ 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)