@ssheleg/make-skill 0.8.0 → 0.9.0

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

@@ -2,6 +2,11 @@
 name: make-skill
 description: Use when creating, upgrading, auditing, or publishing agent skills and Claude Code plugins - "make a skill" / "сделай скилл", "new skill" / "новый скилл", "wrap it in a plugin" / "заверни в плагин", "publish a skill" / "опубликуй скилл", "retrofit a skill to the standard" / "приведи скилл к стандарту", "does this skill match the spec" / "соответствует ли скилл стандарту", "plugin.json / marketplace.json" / "claude plugin validate fails" / "проверь плагин по документации Anthropic", "is this skill safe to install" / "безопасно ли ставить этот скилл" - or when a skill must reach an MCP server or another agent over A2A. Encodes the Agent Skills open standard AND Anthropic's platform rules (front-matter limits, disclosure budgets, Skills API surfaces, evals), the Claude Code plugin reference (manifest schemas, component layout, validate --strict), plus the proven ssheleg pipeline - marketplace layout, version sync, validator+CI, multi-agent distribution, npm gotchas, end-to-end first publish.
 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.9.0"
+  homepage: https://github.com/ssheleg/make-skill
 ---
 
 # make-skill — Create, Retrofit, and Ship Skills the Proven Way
@@ -19,6 +24,8 @@ Copy from a working repo (usually `~/DATA/<name>`): **`ssheleg/super-ux`**
 | `references/authoring.md` | writing or tuning a body/description — naming, third-person rule, degrees of freedom, script rules, eval loops |
 | `references/surfaces.md` | shipping anywhere but Claude Code — Skills API upload/versions/8-per-request, claude.ai zip, the no-network / no-install limits |
 | `references/enterprise.md` | installing someone else's skill, or governing a fleet — risk tiers, review checklist, approval gates, lifecycle, recall limits |
+| `references/retrofit.md` | auditing an existing skill/repo — the 13-item checklist, the evidence rules, the short form for personal skills |
+| `references/host-capabilities.md` | shipping a **hook, subagent, command, script or MCP dependency** — what each buys and costs, hook events/exit codes, and the degradation clauses that keep the skill working without them |
 | `references/claude-code-plugin.md` | anything shipping as a **Claude Code plugin/marketplace** — manifest schemas, component layout, LSP/monitors, path variables, `validate` failures |
 | `references/distribution.md` | the repo layout, publishing, channels, releases |
 | `references/mcp.md` | the skill calls/wraps/documents an **MCP** server, or you're choosing skill vs server |
@@ -109,23 +116,56 @@ House additions on top of the spec:
   passes; a skill built without a baseline documents imagined problems. Adding a
   member to an existing family → test **coexistence**: a broad description
   steals the triggers of the skills already installed.
-- Ship a one-command entry point `/<name>`: idempotent — inspect state → repair
-  missing pieces → status report → exactly ONE suggested next action. Detect
-  mode, never ask. (Pattern: super-ux `/ux`.) **The skill IS that command** —
-  a `commands/<name>.md` beside `skills/<name>/` registers `/<name>` twice; add
-  a `commands/*.md` only under a DIFFERENT name, with a quoted `argument-hint`.
+- Ship a one-command entry point: idempotent — inspect state → repair missing
+  pieces → status report → exactly ONE suggested next action. Detect mode, never
+  ask. (Pattern: super-ux `/ux`.) **The skill IS that command** — a
+  `commands/<name>.md` beside `skills/<name>/` registers the same command twice;
+  add a `commands/*.md` only under a DIFFERENT name, with a quoted
+  `argument-hint`. The invocation differs by channel: `/<skill>` from a skills
+  directory, `/<plugin>:<skill>` once it is installed as a plugin — write both
+  in the README rather than promising one.
 - Never overwrite user data: seed only when absent; overwrite only behind
   `--force`.
 
+### Degradation contract (every skill that touches a host capability)
+
+Hooks, subagents, `/commands`, `${CLAUDE_PLUGIN_ROOT}` and MCP servers exist only
+inside Claude Code — which is a minority of where skills run. **Each is an
+accelerator with a written fallback; the skill still finishes its job without
+it, more slowly.** Write the three cases into the body, in the agent's words, at
+the point it will need them (shapes and wording:
+`references/host-capabilities.md`):
+
+- **Not Claude Code** (Cursor, Codex, skills CLI, API): no hooks, no subagents,
+  no `/command`. Name the inline procedure. Bundled `scripts/` still travel —
+  they live inside the skill directory — so give the path for each channel.
+- **Recommended plugin/skill absent**: say once what is degraded, continue on
+  the manual path. A stage that refuses to start because an optional companion
+  is missing is broken, not strict.
+- **Tool, interpreter or MCP server absent**: state it once, fall back to the
+  by-hand procedure, never retry in a loop. Interactive auth is a human step.
+
+A fallback you know but did not write is not a fallback.
+
+### Working examples this skill ships — copy these, not your memory
+
+`scripts/audit_skill.py` audits ANY skill dir (stdlib; the mechanical half of a
+Retrofit). Beside it: `hooks/` (PostToolUse, exits 0 silently unless a `SKILL.md`
+was written), `commands/skill-audit.md` (deliberately NOT the skill's name),
+`agents/skill-auditor.md`, and six skeletons —
+`assets/SKILL.template.md`, `assets/plugin.template.json`,
+`assets/marketplace.template.json`, `assets/hooks.template.json`,
+`assets/agent.template.md`, `assets/command.template.md`.
+
 ## Create (personal)
 
-`~/.claude/skills/<name>/SKILL.md` following the authoring rules — done. No
-repo, no versioning; loads next session. Mention Promote as the upgrade path.
+`~/.claude/skills/<name>/SKILL.md` per the authoring rules — done. No repo, no
+versioning; loads next session. Mention Promote as the upgrade path.
 
 Needs hooks, an agent, or an MCP server too, still with no repo? Add
 `.claude-plugin/plugin.json` to that same folder — Claude Code loads it as
-`<name>@skills-dir` next session, no marketplace, no install
-(`claude plugin init <name> --with hooks mcp` scaffolds it).
+`<name>@skills-dir` next session (`claude plugin init <name> --with hooks mcp`
+scaffolds it).
 
 ## Create (distributable)
 
@@ -145,6 +185,8 @@ writing the first file.** What holds regardless:
 - **Both `--strict` runs green, in CI, as their own job** — and they read
   MANIFESTS only, so front-matter rules live 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 in the marketplace
+  ENTRY (the marketplace root takes neither `displayName` nor `homepage`).
 - A public repo owes a reader an English-first README, `CONTRIBUTING.md` with
   the offline commands that verify a change, and `SECURITY.md` naming a private
   channel and what the installers touch.
@@ -153,56 +195,29 @@ writing the first file.** What holds regardless:
 
 Take it ALL the way: GitHub + CI green + npm published + verified installs, no
 half-done handoffs. Only the first publish needs a human (npm 2FA); **arming CI
-publishing is part of shipping**, so the second one does not.
-
-**The 11-step sequence is in `references/distribution.md` → *First publish*.**
-Everything green BEFORE publishing, and done = five VERIFIED facts: repo + CI
-green, npm resolvable via npx, plugin installed, skills-CLI discovery working,
-next tag publishing without a human.
+publishing is part of shipping**, so the second one does not. **The 11-step
+sequence is in `references/distribution.md` → *First publish*.** Everything
+green BEFORE publishing; done = five VERIFIED facts: repo + CI green, npm
+resolvable via npx, plugin installed, skills-CLI discovery working, next tag
+publishing without a human.
 
 ## Retrofit (bring an existing skill/repo up to standard)
 
 Audit first, fix second, in the same session. Verdict per item: PASS / GAP with
-evidence (`file:line` or command output) — never "looks fine".
-
-1. **Spec floor** (`references/agent-skills-spec.md`): name charset + ≤64 +
-   ==dir + no reserved word or angle bracket; description ≤1024, "Use when…",
-   third person, EN and RU triggers; no front-matter key outside spec ∪ host
-   extensions; body <500 lines / <5000 tokens; every bundled file one level
-   deep, linked from the body with a load trigger, `## Contents` past 100 lines.
-2. **Anthropic floor** if it ships as a plugin
-   (`references/claude-code-plugin.md`): both `claude plugin validate <plugin
-   dir|.> --strict` runs exit 0; `$schema` present; components at the plugin
-   root, never inside `.claude-plugin/`; `claude plugin details <name>` token
-   cost worth paying.
-3. **Surface honesty** (`references/surfaces.md`): every runtime need (network,
-   packages, MCP server) declared in `compatibility`; no script assuming an
-   install the target surface forbids.
-4. One-job check; shared contracts INSIDE the skill dir — verify by installing
-   via the skills CLI and checking the files actually arrived.
-5. Entry-point command exists, idempotent (inspect → repair → status → one next
-   action).
-6. Layout matches the tree; manifests complete; version sync ×4 (×5 with
-   `metadata.version`).
-7. Validator present, green, and able to fail (run the negative test); CI
-   present, last run `success`.
-8. **Evals exist** in `test/evals/` (`references/authoring.md`): ≥3 scenarios
-   plus should-NOT-trigger queries, coexistence checked against the installed
-   set, re-run on every model the skill claims.
-9. README: badges (npm/CI/license), install + update matrix, English-first,
-   bundled `references/` listed so a reader sees what ships.
-10. Distribution live-checks (`references/distribution.md`): `npx --yes skills
-    add <repo> --list` lists ONLY real skills; `npx <name>` works from a
-    non-repo cwd (if npm published); `.mdc` rules valid, no relative links.
-11. Repo meta: homepage + description + topics on the forge; LICENSE; CHANGELOG
-    current; public repos also CONTRIBUTING.md + SECURITY.md.
-12. Gotcha compliance: the list below, plus the installer traps in
-    `references/distribution.md` if the repo ships a CLI or validator.
-13. MCP or A2A involved: see Protocol-connected skills below.
+evidence — a `file:line` or the output of the command you actually ran. "Looks
+fine" is not a verdict, and neither is a PASS on a check that was reasoned about
+instead of executed.
+
+**Run `scripts/audit_skill.py <dir> --house` first** — it does the mechanical
+half deterministically — **then work the 14-item checklist in
+`references/retrofit.md`**, which covers the spec floor, the Anthropic plugin
+floor, surface honesty, one-job, entry point, layout and version sync, validator
+and CI, evaluations, README, distribution live-checks, repo meta, gotchas,
+protocol dependencies, and host capabilities with their fallbacks. For a
+PERSONAL skill only three items apply — that file says which.
 
 **Then:** report the gap table, fix everything fixable now, bump a minor/patch
-version, run the release checklist. For a PERSONAL skill, retrofit = items 1, 4,
-5 only.
+version, run the release checklist.
 
 ## Promote (personal → distributable)
 
@@ -213,29 +228,25 @@ AFTER the plugin install is verified — duplicate listings confuse agents.
 
 ## Distribution matrix
 
-Five filesystem channels: **Claude Code plugin** (`marketplace add` → `install
-<name>@<name>`), **vercel skills CLI** (`npx skills add <owner>/<repo>`, 70+
-agents, reads `marketplace.json`), **npx** (`npx github:<owner>/<repo>`),
-**Cursor** (skills CLI `--agent cursor --global`, or `.cursor/rules/*.mdc`),
-**umbrella family repo** (`ssheleg/sshlg-skills`). Anthropic's own surfaces —
-Skills API upload (workspace-wide, 8 per request) and claude.ai zip (per user,
-no admin push) — are separate deployments syncing with nothing:
+Five filesystem channels — Claude Code plugin, vercel skills CLI (70+ agents,
+reads `marketplace.json`), npx, Cursor, umbrella family repo — with the exact
+flags in **`references/distribution.md`; read it before publishing, adding a
+channel, or auditing distribution.** Anthropic's own surfaces (Skills API
+upload, claude.ai zip) are separate deployments syncing with nothing:
 `references/surfaces.md`.
 
-**Read `references/distribution.md` before publishing, adding a channel, or
-auditing distribution.** Two rules survive without it: **one channel per agent**
-(never `claude-code` via the skills CLI when a plugin is installed), and **e2e
-`npx` from a non-repo cwd**.
+Two rules survive without opening either: **one channel per agent** (never
+`claude-code` via the skills CLI when a plugin is installed), and **e2e `npx`
+from a non-repo cwd**.
 
 ## Installing someone else's skill
 
 A skill is instructions an agent executes plus code it runs without reading —
 installing one is installing software. Anything not written here gets the
-`references/enterprise.md` review first: scripts read end to end, network calls
-and credentials grepped for, instructions checked for "ignore previous rules",
-hidden actions, or data routed outward. Highest-risk shape: a skill that fetches
-instructions from a URL — that content changes after your review. Same file for
-the fleet rules (approval gates, lifecycle, recall limits).
+`references/enterprise.md` review first: every file read, network calls and
+credentials grepped for, instructions checked for "ignore previous rules",
+hidden actions, or data routed outward. Highest-risk shape: a skill fetching
+instructions from a URL — that content changes after your review.
 
 ## Protocol-connected skills (MCP / A2A)
 
@@ -266,34 +277,31 @@ Non-negotiables for any such skill:
 
 ## Gotchas (each cost a debugging round)
 
-- **npm publishing has its own trap list** — 2FA/EOTP, the name-similarity 403
-  `npm view` can't predict, auth failures masked as 404 on PUT, read-replica lag
-  after a first scoped publish, `npx` resolving locally inside the package's own
-  repo. Fixes in `references/distribution.md` → **read it before any publish.**
+- **npm publishing has a five-trap list** — 2FA/EOTP, a name-similarity 403 that
+  `npm view` cannot predict, auth failures masked as 404, read-replica lag, and
+  `npx` resolving locally inside the package's own repo. Each with its fix in
+  `references/distribution.md` → **read it before any publish.**
 - **A stray `SKILL.md` anywhere in the repo ships as a REAL skill** — the skills
   CLI discovers every one in the tree, so `templates/SKILL.md` lands in every
   agent as a placeholder (seen live: a skill named `<skill-name>`). Name
   skeletons `SKILL.template.md`, have the validator reject any `SKILL.md`
   outside the skill dirs, verify with `npx skills add <repo> --list`.
-- **Quote every `argument-hint`.** Bare `[a | b]` is a YAML flow sequence — one
-  comma drops the whole front-matter block, leaving a command with no
-  description and no warning.
-- **Never name a `commands/<x>.md` after a `skills/<x>/`** — same name, two
-  components: the skill wins and the command is unreachable always-on cost
-  (~100 tok/session here). Check with `claude plugin details`.
+- **Commands: quote every `argument-hint`** (bare `[a | b]` is a YAML flow
+  sequence — one comma drops the whole front-matter block, silently) and **never
+  name one after a skill** in the same plugin (both claim `/<x>`, the skill wins,
+  the command is unreachable always-on cost). Details:
+  `references/host-capabilities.md`.
 - **Writing the installer or validator?** Four more traps (piped-stdin readline,
   raw-mode pickers, ANSI literals, python 3.9 drift) are in
   `references/distribution.md` → *Installer implementation traps*.
 - **gh auth status may lie** (invalid-token report while git+ssh works): attempt
   the operation before declaring it blocked.
-- **Duplicate-shadow: one channel per agent — and the shadow regrows.** A plugin
-  install AND a plain `~/.claude/skills/<name>` copy = two listings, and the
-  plain (usually STALE) one wins. `npx skills add|update … --global` recreates
-  that path **even when `claude-code` was never targeted**, so the prune belongs
-  in the update command: `npx skills update <name> --global --yes && rm -f
-  ~/.claude/skills/<name>`.
-- **Plugin commands need the full `<name>@<name>`:** `claude plugin update
-  <name>` → "Plugin not found". Same for install.
+- **Duplicate-shadow: the stale copy wins, and it regrows.** A plugin install
+  plus a plain `~/.claude/skills/<name>` copy = two listings; `npx skills
+  add|update … --global` recreates that path **even when `claude-code` was never
+  targeted**, so the prune belongs inside the update command: `npx skills update
+  <name> --global --yes && rm -f ~/.claude/skills/<name>`. Plugin commands also
+  need the full id — `claude plugin update <name>` answers "Plugin not found".
 - **A pinned `version` you forget to bump freezes every user.** The version is
   the update cache key: twenty commits under `0.6.1` and `/plugin update` still
   says "already at the latest version". (Omitting it from both manifests is
@@ -301,6 +309,12 @@ Non-negotiables for any such skill:
 - **Time-branching text rots.** "Before August, use the old API" is wrong the day
   it ships — superseded material goes under `## Old patterns`, and a dated
   provenance line ("*read from the spec on 2026-08-03*") ages well.
+- **Two token counters, ~40% apart.** `claude plugin details` reported ~7.2k
+  on-invoke for a SKILL.md that a real tokenizer puts at ~5.0k (measured across
+  six installed skills: the CLI assumes ~2.8 chars/token, cl100k gives 3.8–4.5).
+  Its estimator is the pessimistic one — budget against a tokenizer, then expect
+  the CLI to show a bigger number, and never "fix" a body that is already
+  inside 5000 real tokens because the CLI looked alarming.
 
 ## Release (every version)
 

package/plugins/make-skill/skills/make-skill/assets/agent.template.md

@@ -0,0 +1,33 @@
+---
+name: agent-name-here
+description: What this agent does and WHEN the main thread should delegate to it. Third person, concrete triggers — the same selection problem a skill description solves.
+tools: Read, Grep, Glob, Bash
+# Optional: model, effort, maxTurns, disallowedTools, memory, background,
+#           isolation: "worktree"  (only value accepted)
+# REJECTED for plugin-shipped agents: hooks, mcpServers, permissionMode
+---
+
+You <one sentence: the single job>. You do not <the adjacent job you must refuse>.
+
+## Procedure
+
+1. Deterministic step first — run the bundled script rather than reasoning your
+   way to the same answer:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/skills/SKILL_NAME/scripts/SCRIPT.py" <target>
+   ```
+
+   No `${CLAUDE_PLUGIN_ROOT}`? You are not running as a Claude Code plugin —
+   find the script under the skill directory you were loaded from. Interpreter
+   missing? Say so once and do the checks by hand from the reference; a missing
+   tool changes how you work, not whether you report.
+
+2. Judgement steps, each naming the reference file that carries the rules. Read
+   the file; do not reconstruct it from memory.
+
+## Output
+
+Exactly what the caller needs and nothing else — a table, a verdict, or a patch.
+Evidence for every claim (`file:line` or command output). Finish with ONE next
+action and stop.

package/plugins/make-skill/skills/make-skill/assets/command.template.md

@@ -0,0 +1,32 @@
+---
+description: "One line the user sees in the / menu — what it does, not how it works"
+argument-hint: "[what to pass] [--flag]"
+---
+
+<!--
+Two rules this skeleton exists to enforce:
+
+  1. NEVER name this file after a skill directory in the same plugin. Commands
+     are skills now: `commands/x.md` beside `skills/x/` registers /x twice, the
+     skill wins, and the command is unreachable always-on token cost.
+  2. ALWAYS quote `argument-hint`. A bare [a | b] is a YAML flow sequence; one
+     comma inside it drops the whole frontmatter block, leaving a command with
+     no description and no warning.
+-->
+
+Do <the task> for `$ARGUMENTS`.
+
+1. The deterministic part, by script:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/skills/SKILL_NAME/scripts/SCRIPT.py" $ARGUMENTS
+   ```
+
+   Not running as a Claude Code plugin, so `${CLAUDE_PLUGIN_ROOT}` is unset? The
+   script is in the skill directory this file was installed beside. No
+   interpreter? Fall back to the manual procedure in the reference and say that
+   you did.
+
+2. The judgement part, from `references/FILE.md`.
+
+3. Report: what was checked, what the verdict is, and ONE next action.

package/plugins/make-skill/skills/make-skill/assets/hooks.template.json

@@ -0,0 +1,32 @@
+{
+  "description": "PLUGIN_NAME — one sentence on what these hooks do, and the sentence that matters to a reviewer: when they no-op. A globally installed plugin must be invisible in projects that do not use it.",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/HOOK_SCRIPT.sh\"",
+            "timeout": 20,
+            "statusMessage": "What the user sees while this runs"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/SESSION_SCRIPT.sh\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/{templates → plugins/make-skill/skills/make-skill/assets}/marketplace.template.json

@@ -9,6 +9,7 @@
   "plugins": [
     {
       "name": "<plugin-name>",
+      "displayName": "<Plugin Name>",
       "source": "./plugins/<plugin-name>",
       "description": "<what the plugin gives an agent>",
       "version": "0.1.0",

package/{templates → plugins/make-skill/skills/make-skill/assets}/plugin.template.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "<plugin-name>",
+  "displayName": "<Plugin Name>",
   "description": "<what the plugin gives an agent, in one sentence>",
   "version": "0.1.0",
   "author": {

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

@@ -180,6 +180,13 @@ if written carelessly.
 - **Vision is available**: rendering an input to images and letting the agent look
   at it beats describing a layout in prose.
 
+Worked example: this skill's own `scripts/audit_skill.py`. It is stdlib-only so
+it runs wherever the skill landed, prints `file:line` evidence rather than
+verdicts, handles its own missing-file and bad-frontmatter cases, and its first
+run flagged a false positive on the very document that teaches the anti-pattern —
+which is why it now ignores quoted spans. Hooks, subagents and commands that wrap
+it, plus the fallbacks they owe, are in `references/host-capabilities.md`.
+
 ## Evaluation and iteration — evals before prose
 
 **Build the evaluations before writing extensive documentation.** Otherwise the

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

@@ -22,8 +22,8 @@ must also run on Cursor, Codex, or the skills CLI.
 ## Contents
 
 - The gate: `claude plugin validate`
-- `plugin.json` fields
-- `marketplace.json` fields, reserved names, plugin entries
+- `plugin.json` — `.claude-plugin/plugin.json` (field table)
+- `marketplace.json` — `.claude-plugin/marketplace.json` (fields, reserved names, plugin entries)
 - Component locations
 - Skill frontmatter — host extensions
 - Agents, hooks, MCP inside a plugin

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

@@ -19,6 +19,8 @@ API or claude.ai instead is `references/surfaces.md`.
 - Release checklist (every version)
 - Toggleable release automation
 
+## The shadow rule (one channel per agent)
+
 Hard rule across all channels: **one channel per agent.** Two installs of the same
 skill on one agent = two listings, and the stale copy shadows the fresh one.
 
@@ -46,10 +48,13 @@ the shape from `ssheleg/super-ux`:
 ├── .claude-plugin/marketplace.json     # root manifest, plugins[0].source: ./plugins/<name>
 ├── plugins/<name>/
 │   ├── .claude-plugin/plugin.json      # ONLY the manifest lives in .claude-plugin/
-│   └── skills/<skill>/SKILL.md  +  references/*.md (+ scripts/, assets/)
-│       (commands/*.md too — but never named after a skill)
+│   ├── skills/<skill>/SKILL.md  +  references/*.md  +  scripts/  +  assets/
+│   │                                   # skeletons live HERE, not at the repo root:
+│   │                                   # only the skill dir travels on every channel
+│   ├── hooks/hooks.json + *.sh         # Claude Code only — see host-capabilities.md
+│   ├── agents/*.md                     # Claude Code only
+│   └── commands/*.md                   # never named after a skill
 ├── cursor/rules/*.mdc                  # if agent-rules make sense for Cursor
-├── templates/*.md                      # skeletons (NEVER name one SKILL.md)
 ├── bin/<name>.js + package.json        # npx installer (zero-dep Node)
 ├── test/validate.py                    # consistency validator (stdlib only)
 ├── test/evals/                         # triggers.json + scenarios.json (data, run by a human)
@@ -57,15 +62,23 @@ the shape from `ssheleg/super-ux`:
 ├── install.sh                          # POSIX fallback
 ├── README.md (English-first), CHANGELOG.md, LICENSE (MIT)
 ├── CONTRIBUTING.md + SECURITY.md       # public repo: how to check work, where to report
+├── SKILL-CARD.md                       # the enterprise registry entry + risk-table pass
 └── docs/superpowers/{specs,plans}/
 ```
 
 **Public-repo floor** (validator-enforced): a README saying what it does before
 how to install it, **English-first** — Russian belongs in trigger phrases, where
 it changes whether the skill fires; `CONTRIBUTING.md` with the offline commands
-that verify a change; `SECURITY.md` naming a private reporting channel and what
-the installers touch. A skill is text an agent executes, so "review before
-installing" belongs in writing.
+that verify a change; `SECURITY.md` naming a private reporting channel and every
+path that executes, hooks first; `SKILL-CARD.md` answering the enterprise
+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`).
 
 **Version sync (hard rule):** `marketplace.json`, `plugin.json`, `package.json`
 and the top CHANGELOG entry carry the SAME semver, bumped together; the validator