@ssheleg/make-skill 0.7.1 → 0.8.1

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

@@ -1,28 +1,52 @@
-# Agent Skills open standard — conformance reference
+# Agent Skills — the hard rules, from both authorities
 
 **Load this when:** authoring or retrofitting any `SKILL.md`, or when a skill must
-install cleanly on agents outside Claude Code.
+install cleanly outside Claude Code. Craft (descriptions, freedom, scripts, evals)
+is `references/authoring.md`; surfaces and the Skills API are
+`references/surfaces.md`.
 
-Upstream sources (verify before locking anything — the spec moves):
-- Spec — <https://agentskills.io/specification>
-- Repo + reference validator — <https://github.com/agentskills/agentskills>
-  (`skills-ref validate ./my-skill`; Python, installed from source out of that
-  repo — it is not on npm or PyPI)
-- Best practices — <https://agentskills.io/skill-creation/best-practices>
-- Description tuning — <https://agentskills.io/skill-creation/optimizing-descriptions>
+## Contents
 
-*Field limits and budgets below were read from the spec on 2026-07-28. Re-read
-before trusting them in a new quarter.*
+- Two authorities, one floor
+- Frontmatter — the whole field set
+- Notes that bite
+- Directory layout
+- Progressive disclosure — the budgets
+- Validation — who says no
+- Conformance checklist
 
-The ssheleg canon in `SKILL.md` is a **superset** of this spec. It may add rules
+## Two authorities, one floor
+
+| Source | What it governs | Where |
+|---|---|---|
+| **Agent Skills open standard** | the portable format every agent reads | <https://agentskills.io/specification> |
+| **Anthropic platform docs** | what Anthropic's own surfaces accept and enforce | <https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview> |
+| Claude Code plugin reference | host extensions and packaging | `references/claude-code-plugin.md` |
+
+They agree on the shape and differ on enforcement — **write to the intersection**,
+because the strictest reader is the one that rejects you:
+
+| Rule | agentskills.io | Anthropic platform | Claude Code |
+|---|---|---|---|
+| `name` ≤64, `[a-z0-9-]` | yes | yes | yes |
+| no leading/trailing/double hyphen, `name` == parent dir | **required** | dir must match `name` on upload (case/underscore-insensitive) | `name` overrides the dir for the `/command` |
+| `name` must not contain `anthropic` / `claude` | silent | **enforced** — the Skills API rejects the upload | not enforced |
+| no XML tags in `name` / `description` | silent | **enforced** | not enforced |
+| `description` ≤1024, non-empty | yes | yes | listing truncates `description` + `when_to_use` at 1536 |
+| `license`, `compatibility`, `metadata`, `allowed-tools` | defined | undocumented — don't depend on them there | read, plus ~14 host-only fields |
+| body <500 lines / <5000 tokens | recommended | recommended (level-2 budget) | same |
+
+*Read from both on 2026-08-03. Re-read before trusting a limit in a new quarter.*
+
+The ssheleg canon in `SKILL.md` is a **superset** of all three. It may add rules
 (RU triggers, version sync, marketplace layout); it must never violate one.
 
 ## Frontmatter — the whole field set
 
 | Field | Required | Constraint |
 |---|---|---|
-| `name` | yes | 1–64 chars, `a-z0-9-` only, no leading/trailing `-`, no `--`, MUST equal the parent directory name |
-| `description` | yes | 1–1024 chars, non-empty; says what it does AND when to use it |
+| `name` | yes | 1–64 chars, `a-z0-9-` only, no leading/trailing `-`, no `--`, MUST equal the parent directory name, no XML tags, must not contain `anthropic` or `claude` |
+| `description` | yes | 1–1024 chars, non-empty, no XML tags; says what it does AND when to use it; third person |
 | `license` | no | license name or the name of a bundled license file |
 | `compatibility` | no | ≤500 chars; environment requirements (product, system packages, network) |
 | `metadata` | no | map of string→string; arbitrary client-defined keys (use unique key names) |
@@ -41,9 +65,15 @@ allowed-tools: Bash(git:*) Read
 ---
 ```
 
-Notes that bite:
+## Notes that bite
+
 - The **1024-char cap is on `description` alone**, not on the whole frontmatter
   block. Adding `license`/`metadata` does not eat the description budget.
+- **Reserved words are a substring rule.** `claude-tools`, `anthropic-helper` and
+  `my-claude-thing` are all rejected on upload — legal in Claude Code, so the
+  failure only appears the day someone ships the skill to the API.
+- **"No XML tags" bites templates.** A placeholder like `name: <skill-name>` reads
+  as a tag; seed skeletons with plain placeholders (`skill-name-here`).
 - `metadata` values are **strings** — quote versions (`version: "1.0"`), or YAML
   turns `1.0` into a float.
 - `allowed-tools` is a single space-separated **string**, not a YAML list. Claude
@@ -52,6 +82,8 @@ Notes that bite:
 - Nothing in the spec versions a skill. If you want the version visible to agents
   that never see `plugin.json`, put it in `metadata.version` — then it joins the
   version-sync rule.
+- The 500-line / 5000-token budget is on the body an agent loads on activation,
+  not on the bundle. Bundled files cost nothing until read.
 
 ## Directory layout
 
@@ -71,6 +103,7 @@ Notes that bite:
   dir), never in a sibling directory: the skills CLI ships only the skill's own
   folder.
 - `assets/` — output templates too long for `SKILL.md`, schemas, lookup tables.
+- Paths are relative to the skill root and always use **forward slashes**.
 
 ## Progressive disclosure — the budgets
 
@@ -81,67 +114,44 @@ Notes that bite:
 | `scripts/` `references/` `assets/` | only when the body sends the agent there | no cap, keep files focused |
 
 Rules:
-- Relative paths from the skill root; keep references **one level deep**
-  (`references/mcp.md`, not `references/proto/v1/mcp.md`). No reference chains.
-- State **when** to load each file — "read `references/a2a.md` before designing
-  an agent-to-agent contract" beats "see references/ for details". An unconditional
+- Keep references **one level deep** (`references/mcp.md`, not
+  `references/proto/v1/mcp.md`) and link every one of them from `SKILL.md`
+  itself. A file reachable only through another file gets previewed with `head`
+  and half-read.
+- Give every reference a **load condition** — "read `references/a2a.md` before
+  designing an agent-to-agent contract" beats "see references/". An unconditional
   pointer gets loaded always or never.
+- Reference files over **100 lines carry a `## Contents` list** — that is what a
+  partial read sees.
 - Keep gotchas in `SKILL.md` itself. The agent can't know to load a file about a
   trap it doesn't know exists.
+- Scripts are executed, not read: their code never enters context, only output
+  does. Say which you mean.
+
+## Validation — who says no
+
+| Checker | Covers | Note |
+|---|---|---|
+| `skills-ref validate ./<skill dir>` | the open standard's frontmatter rules | Python, installed from source out of `github.com/agentskills/agentskills`; not on npm or PyPI |
+| Skills API upload | Anthropic's extra rules (reserved words, XML tags, dir name, 30 MB) | the only place they are enforced — see `references/surfaces.md` |
+| `claude plugin validate … --strict` | plugin/marketplace **manifests only**, not SKILL.md frontmatter | `references/claude-code-plugin.md` |
+| your `test/validate.py` | house rules + everything the three above miss | the only one that runs on every commit |
+
+## Conformance checklist
 
-## Description — the whole triggering budget
-
-The description is the ONLY thing the agent sees before deciding to load the
-skill. Spec-aligned rules:
-
-- **Imperative**: "Use when …", not "This skill does …".
-- **User intent, not mechanics** — match what the user asked for.
-- **Be pushy**: name the contexts where it applies, including ones where the user
-  never says the domain word ("even if they don't mention 'CSV'").
-- **Concise**: a few sentences. Descriptions grow during tuning — re-check the
-  1024 cap after every edit.
-- Agents skip skills for tasks they can already do in one step. Descriptions earn
-  their keep on specialized/multi-step work.
-
-### Trigger eval loop (use when a skill fires too rarely or too often)
-
-1. Write ~20 realistic queries: 8–10 `should_trigger: true`, 8–10 `false`. The
-   valuable negatives are **near-misses** that share keywords but need something
-   else.
-2. Run each 3× against the agent with the skill installed → trigger rate;
-   pass threshold 0.5.
-3. Split 60% train / 40% validation, fixed across iterations. Tune only on train
-   failures.
-4. Too narrow → broaden scope/context. False-firing → add what it does NOT do.
-   Never paste keywords from a failed query — that's overfitting; address the
-   category instead.
-5. ≤5 iterations; pick the iteration with the best **validation** pass rate (not
-   necessarily the last).
-
-## Body patterns worth copying
-
-- **Gotchas section** — concrete environment facts that defy assumption. Highest
-  value content in most skills. Every correction you make by hand becomes a line.
-- **Templates** for output format — agents pattern-match structures better than
-  prose descriptions. Long ones → `assets/`.
-- **Checklists** for multi-step workflows with dependencies.
-- **Validation loops** — do work → run validator → fix → repeat until green.
-- **Plan-validate-execute** for batch/destructive work: emit a plan file, validate
-  it against a source-of-truth file, only then execute.
-- **Defaults, not menus** — one recommended tool + a one-line escape hatch.
-- **Add what the agent lacks**; cut anything it already knows. Test: "would the
-  agent get this wrong without this line?" No → delete it.
-- **Procedures over answers** — teach the method, not one instance's result.
-
-## Conformance checklist (run in every Retrofit audit)
-
-- [ ] `name`: matches dir, ≤64 chars, `[a-z0-9-]`, no leading/trailing/double hyphen
-- [ ] `description`: 1–1024 chars, imperative "Use when …", triggers listed
+- [ ] `name`: matches dir, ≤64 chars, `[a-z0-9-]`, no leading/trailing/double
+      hyphen, no `anthropic`/`claude`, no angle brackets
+- [ ] `description`: 1–1024 chars, no angle brackets, third person, says what it
+      does AND when to use it, concrete triggers listed
 - [ ] optional fields legal: `compatibility` ≤500, `metadata` all-string map,
       `allowed-tools` a space-separated string
+- [ ] no frontmatter key outside spec ∪ documented host extensions
 - [ ] `SKILL.md` < 500 lines and < 5000 tokens
-- [ ] heavy material lives in `references/` / `scripts/` / `assets/` INSIDE the
-      skill dir, one level deep, each with a stated load trigger
-- [ ] no relative link escapes the skill directory (`../`)
+- [ ] heavy material in `references/` / `scripts/` / `assets/` INSIDE the skill
+      dir, one level deep, each linked from the body with a stated load trigger
+- [ ] reference files >100 lines have a `## Contents` list
+- [ ] forward slashes everywhere; no relative link escapes the skill dir (`../`)
+- [ ] runtime needs (network, packages) declared in `compatibility` —
+      `references/surfaces.md`
 - [ ] `skills-ref validate ./<skill dir>` passes (upstream truth), in addition to
       `test/validate.py` (house rules)

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

@@ -0,0 +1,244 @@
+# Authoring craft — writing a body an agent actually follows
+
+**Load this when:** writing or rewriting a `SKILL.md` body, tuning a description
+that fires too rarely or too often, deciding how prescriptive to be, bundling
+`scripts/`, or building the evaluations that prove the skill works.
+
+Hard limits and field rules are in `references/agent-skills-spec.md`; this file is
+the craft on top of them. Sources: Anthropic's
+[skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+and [agentskills.io](https://agentskills.io/skill-creation/best-practices).
+*Read from both on 2026-08-03.*
+
+## Contents
+
+- Naming — what to call the skill
+- Description — the entire triggering budget
+- Trigger eval loop — when firing is wrong
+- Degrees of freedom — how prescriptive to be
+- Body patterns worth copying
+- Workflows and feedback loops
+- Content guidelines (terminology, time, paths, table of contents)
+- Scripts — the rules that separate a script from a liability
+- Evaluation and iteration — evals before prose
+- Quality checklist
+
+## Naming — what to call the skill
+
+The `name` is a trigger surface, not a filename. Charset rules live in the spec
+reference; the naming *style* rules:
+
+- **Gerund form is the recommended default** — `processing-pdfs`,
+  `analyzing-spreadsheets`, `writing-documentation`. It states the activity.
+- Acceptable: noun phrase (`pdf-processing`), action form (`process-pdfs`).
+- **Never**: `helper`, `utils`, `tools`, `documents`, `data`, `files` — a vague
+  name buys nothing at selection time and collides with the next skill.
+- **Never** `anthropic`/`claude` in the name — reserved, and the Skills API
+  rejects the upload (see the spec reference).
+- Pick ONE pattern per collection and hold it. Mixed patterns inside a family are
+  the reason nobody can guess a sibling skill's name.
+
+## Description — the entire triggering budget
+
+The description is the only thing an agent sees before deciding to load the
+skill, and it competes with every other installed skill's description. Rules,
+each of which changes whether the skill fires:
+
+- **Say both halves: what it does AND when to use it.** "Extracts text and tables
+  from PDFs, fills forms, merges documents. Use when working with PDF files or
+  when the user mentions PDFs, forms, or document extraction."
+- **Third person, always.** The description is injected into the system prompt;
+  first/second person ("I can help you…", "You can use this to…") measurably
+  degrades selection. Imperative "Use when …" is fine — it is the trigger clause,
+  not a point of view.
+- **User intent, not mechanics.** Match the words the user will actually type.
+- **Be pushy about context**: name the situations where it applies, including the
+  ones where the user never says the domain word ("even if they don't mention
+  'CSV'").
+- **Say what it is NOT for** when a near-miss skill exists. That sentence is what
+  stops trigger theft.
+- Concise, a few sentences. Descriptions grow during tuning — re-check the 1024
+  cap after every edit.
+- Vague descriptions are the failure mode: `Helps with documents`, `Processes
+  data`, `Does stuff with files` never win a selection against a specific one.
+- Agents skip skills for tasks they can already do in one step. Descriptions earn
+  their keep on specialized or multi-step work.
+
+## Trigger eval loop — when firing is wrong
+
+1. Write ~20 realistic queries: 8–10 `should_trigger: true`, 8–10 `false`. The
+   valuable negatives are **near-misses** that share keywords but need something
+   else.
+2. Run each 3× against the agent with the skill installed → trigger rate;
+   pass threshold 0.5.
+3. Split 60% train / 40% validation, fixed across iterations. Tune only on train
+   failures.
+4. Too narrow → broaden scope/context. False-firing → add what it does NOT do.
+   Never paste keywords from a failed query — that's overfitting; address the
+   category instead.
+5. ≤5 iterations; pick the iteration with the best **validation** pass rate (not
+   necessarily the last).
+
+## Degrees of freedom — how prescriptive to be
+
+Match specificity to how fragile the task is. Getting this backwards is the most
+common reason a skill is either ignored or actively harmful.
+
+| Freedom | Write | Use when |
+|---|---|---|
+| **High** | prose steps, heuristics | many valid approaches, context decides (code review, triage) |
+| **Medium** | pseudocode, parameterized snippet | a preferred pattern exists, some variation is fine (report generation) |
+| **Low** | one exact command, "do not modify it" | fragile, order-dependent, destructive (migrations, releases) |
+
+The picture: a narrow bridge with cliffs gets guardrails and one exact command;
+an open field gets a direction and trust. A low-freedom instruction in an open
+field makes the agent worse than it was without the skill.
+
+## Body patterns worth copying
+
+- **Gotchas section** — concrete environment facts that defy assumption. Highest
+  value content in most skills. Every correction you make by hand becomes a line.
+- **Templates** for output format — agents pattern-match structures better than
+  prose. Mark them strict ("ALWAYS use this exact structure") or flexible ("a
+  sensible default; use judgement"); an unlabelled template gets both wrong. Long
+  ones → `assets/`.
+- **Input/output example pairs** where quality depends on style (commit messages,
+  reviews). Three examples beat three paragraphs describing them.
+- **Checklists** for multi-step workflows with dependencies.
+- **Conditional routing** — "creating new content? → workflow A; editing? →
+  workflow B" — so the agent never reads the branch it doesn't need.
+- **Validation loops** — do work → run validator → fix → repeat until green.
+- **Plan-validate-execute** for batch/destructive work: emit a plan file, validate
+  it against a source-of-truth file, only then execute. Catches "field does not
+  exist" before 50 fields are written, and the plan is cheap to iterate on.
+- **Defaults, not menus** — one recommended tool plus a one-line escape hatch.
+  "pypdf or pdfplumber or PyMuPDF or pdf2image" is a coin flip, not guidance.
+- **Add what the agent lacks**; cut anything it already knows. Test: "would the
+  agent get this wrong without this line?" No → delete it.
+- **Procedures over answers** — teach the method, not one instance's result.
+
+## Workflows and feedback loops
+
+For anything multi-step, give a checklist the agent can copy into its reply and
+tick off, then the steps beneath it:
+
+```
+Task progress:
+- [ ] Step 1: analyze the form (run scripts/analyze_form.py)
+- [ ] Step 2: create the field mapping (edit fields.json)
+- [ ] Step 3: validate the mapping (run scripts/validate_fields.py)
+- [ ] Step 4: fill the form (run scripts/fill_form.py)
+- [ ] Step 5: verify output (run scripts/verify_output.py)
+```
+
+Explicit steps are what stop an agent skipping validation. Name the return edge:
+"if verification fails, return to step 2". The same shape works with no code at
+all — the "validator" can be a style guide the agent re-reads.
+
+If a workflow grows past a screen, move it into its own file and route to it from
+the body.
+
+## Content guidelines
+
+- **No time-sensitive statements.** "Before August, use the old API" is wrong the
+  moment it ships. Put superseded material under an `## Old patterns` heading (a
+  collapsed `<details>` block works) and keep the current path unqualified. A
+  DATED PROVENANCE line is the exception and is encouraged: "*read from the spec
+  on 2026-08-03*" tells the next reader what to re-verify.
+- **One term per concept.** Pick "field" or "box", "extract" or "pull", and never
+  alternate — synonym drift makes an agent think two things are being described.
+- **Forward slashes in every path**, including on Windows: `scripts/helper.py`,
+  never `scripts\helper.py`. Backslash paths break on Unix and in JSON.
+- **Reference files over 100 lines get a `## Contents` list at the top.** Agents
+  preview long files with `head`; without a table of contents they act on the
+  first 100 lines and never learn the rest exists.
+- **One level deep from `SKILL.md`.** A file reachable only through another file
+  gets partially read or missed entirely. Every reference links from the body.
+
+## Scripts — the rules that separate a script from a liability
+
+A bundled script is more reliable than generated code, costs no context (only its
+output enters the window), and is consistent across runs. It also fails silently
+if written carelessly.
+
+- **Solve, don't defer.** Handle the error inside the script — missing file,
+  permission denied — and print what you did. `return open(path).read()` and
+  "let the agent figure it out" turns one failure into a debugging session.
+- **No voodoo constants.** Every timeout, retry count and threshold carries a
+  comment justifying it. If you don't know why it's 47, the agent has no chance.
+- **State the intent explicitly**: "Run `scripts/analyze_form.py` to extract
+  fields" (execute) vs "See `scripts/analyze_form.py` for the extraction
+  algorithm" (read). Ambiguity here gets a script pasted into context, which is
+  exactly the cost the script existed to avoid.
+- **Declare dependencies and verify they exist** on the surface you target —
+  "install required package: `pip install pypdf`", or better, no third-party
+  dependency at all. Never write "use the pdf library". The Claude API surface
+  cannot install anything at runtime (`references/surfaces.md`).
+- **Verbose, specific error messages**: "Field 'signature_date' not found.
+  Available: customer_name, order_total, signature_date_signed" is actionable;
+  "invalid field" is not.
+- **Vision is available**: rendering an input to images and letting the agent look
+  at it beats describing a layout in prose.
+
+## Evaluation and iteration — evals before prose
+
+**Build the evaluations before writing extensive documentation.** Otherwise the
+skill documents imagined problems.
+
+1. **Identify gaps** — run the agent on representative tasks with NO skill.
+   Record the specific failures.
+2. **Create evaluations** — at least three scenarios covering those gaps.
+3. **Baseline** — measure performance without the skill.
+4. **Write the minimum** that fixes the gaps.
+5. **Iterate** — re-run, compare to baseline, refine.
+
+Evaluation record — there is no built-in runner, so keep them in the repo as
+data and run them yourself. House layout: `test/evals/triggers.json` (~20
+queries, half near-miss negatives) and `test/evals/scenarios.json` (≥3, the
+shape below), with any input under `test/evals/fixtures/` — **never named
+`SKILL.md`**, which would ship as a real skill:
+
+```json
+{
+  "skills": ["pdf-processing"],
+  "query": "Extract all text from this PDF file and save it to output.txt",
+  "files": ["test-files/document.pdf"],
+  "expected_behavior": [
+    "Reads the PDF with an appropriate library or CLI tool",
+    "Extracts text from every page without skipping any",
+    "Saves the result to output.txt in readable form"
+  ]
+}
+```
+
+**Test on every model you ship for.** A skill is an addition to a model, so its
+effect varies by model: Haiku may need more guidance, Opus may be slowed by
+over-explanation. Run the evals on Haiku, Sonnet and Opus if all three are in
+scope.
+
+**The two-agent loop.** Author with one instance (call it A), test with a fresh
+instance that has the skill installed (B), and bring B's observed failures back to
+A — "B forgot to filter test accounts even though the skill says to; is the rule
+prominent enough?". Refine against observed behavior, never against assumptions.
+Watch for: files read in an unexpected order (structure is wrong), references
+never followed (links not prominent), the same file read every time (it belongs in
+the body), a bundled file never read at all (delete it).
+
+Approval gates for a skill other people will install — triggering accuracy,
+isolation, coexistence with the existing skill set, instruction following, output
+quality — are in `references/enterprise.md`.
+
+## Quality checklist
+
+- [ ] Description gives what AND when, in third person, with concrete triggers
+- [ ] Name follows one pattern, is not vague, contains no reserved word
+- [ ] Body under 500 lines / 5000 tokens; detail in one-level-deep files
+- [ ] Every reference has a stated load condition; >100-line ones have a TOC
+- [ ] Degrees of freedom match task fragility
+- [ ] No time-sensitive statements outside an "Old patterns" section
+- [ ] Consistent terminology; forward slashes everywhere
+- [ ] Examples concrete, not abstract; a default given instead of a menu
+- [ ] Scripts handle their own errors, document constants, declare packages
+- [ ] Execute-vs-read intent stated for every bundled script
+- [ ] Validation/feedback loop for anything quality-critical or destructive
+- [ ] ≥3 evaluations exist, baselined without the skill, run on every target model

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

@@ -19,6 +19,21 @@ 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.
 
+## Contents
+
+- The gate: `claude plugin validate`
+- `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
+- LSP servers and monitors
+- Path variables
+- Caching, symlinks, path traversal
+- Skills-directory plugins
+- CLI
+- Conformance checklist
+
 ## The gate: `claude plugin validate`
 
 ```bash

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

@@ -1,7 +1,25 @@
 # Distribution matrix — every channel, with the flags that actually work
 
 **Load this when:** publishing a skill for the first time, adding a channel, or
-auditing an existing repo's distribution in a Retrofit.
+auditing an existing repo's distribution in a Retrofit. Uploading to the Claude
+API or claude.ai instead is `references/surfaces.md`.
+
+## Contents
+
+- The shadow rule (one channel per agent)
+- The distributable repo layout (tree, public-repo floor, version sync, gates)
+- 1. Claude Code plugin
+- 2. vercel-labs skills CLI
+- 3. npx installer — npm gotchas, installer implementation traps
+- First publish — the 11-step sequence
+- 4. Cursor
+- 5. Ship a FAMILY via an umbrella repo
+- Platforms
+- Live-check set (Retrofit)
+- 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.
@@ -20,6 +38,69 @@ Put that prune inside whatever script performs the update, so the supported path
 can't leave a shadow behind. A symlink shadows exactly as a directory does — check
 with `ls -ld`, and remember `find -type f` will not see through it.
 
+## The distributable repo layout
+
+Every rule here exists because the repo ships through more than one channel. Copy
+the shape from `ssheleg/super-ux`:
+
+```
+<repo>/
+├── .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)
+├── 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)
+├── .github/workflows/validate.yml      # validator on push+PR (+ release.yml, off by default)
+├── 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
+└── 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.
+
+**Version sync (hard rule):** `marketplace.json`, `plugin.json`, `package.json`
+and the top CHANGELOG entry carry the SAME semver, bumped together; the validator
+enforces it. An optional `SKILL.md` `metadata.version` — spec-legal, and the only
+version an agent outside Claude Code ever sees — joins as a 5th point.
+
+**Two Claude Code checks, both mandatory** (field tables, sources, reserved
+names: `references/claude-code-plugin.md`):
+
+- **`claude plugin validate <path> --strict` on BOTH manifests, wired into CI**
+  — offline, no auth (`npm i -g @anthropic-ai/claude-code`). Ship `$schema` and
+  `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.
+- **`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.
+
+**The house validator** (adapt super-ux `test/validate.py`, stdlib only) enforces
+what neither upstream gate sees: both conformance checklists
+(`agent-skills-spec.md`, `claude-code-plugin.md`), the house description rules
+(starts "Use when", EN+RU triggers), version sync, references reachable / one
+level deep / `## Contents` past 100 lines, no command colliding with a skill
+name, `.mdc` free of relative links, **no stray `SKILL.md` outside
+`plugins/*/skills/*/`**, links that resolve and never escape the skill dir. Plus
+a negative self-test — corrupt a copy, expect FAIL — because a validator nobody
+has watched fail is decoration. Run `claude plugin validate --strict` as its OWN
+CI job so an upstream outage cannot mask a house failure, and treat `skills-ref
+validate <skill dir>` (from `agentskills/agentskills`) as the tie-breaker on the
+open standard.
+
 ## 1. Claude Code plugin
 
 `/plugin marketplace add <owner>/<repo>` → `/plugin install <name>@<name>`;
@@ -201,3 +282,41 @@ npx skills add <owner>/<repo> --list          # lists ONLY real skills
 npx <name>                                     # from a NON-repo cwd
 claude plugin update <name>@<name>             # full id required
 ```
+
+## Release checklist (every version)
+
+1. Bump the four versions together (`package.json` only if npm-distributed — else
+   it is a 3-way sync); write the CHANGELOG entry.
+2. `python3 test/validate.py` → exit 0 (`PASS: …`), then
+   `claude plugin validate ./plugins/<name> --strict` and
+   `claude plugin validate . --strict` → both exit 0.
+3. Functional tests: installer against a scratch `HOME` (fresh / rerun-skip /
+   `--force`), `node --check` on the CLI, piped-menu tests.
+4. Conventional commit; push; confirm CI `success`; tag `v<ver>` and push the tag;
+   `gh release create` from the CHANGELOG section (or let the release workflow
+   below do it).
+5. npm publish if applicable (human 2FA the first time); e2e `npx <name>@<ver>`
+   from a non-repo cwd.
+6. **Refresh THIS machine's global installs — always, as Definition of Done:**
+   `claude plugin marketplace update <name>` → `claude plugin update
+   <name>@<name>` → `npx skills update <name> --global --yes && rm -f
+   ~/.claude/skills/<name>`; then remind the user to restart the agent.
+7. Family member? Bump its pin in the umbrella `skills.json` and release the
+   umbrella (§5) — until that lands, `list` advertises the old version.
+8. Global `~/.claude/CLAUDE.md` — only for rules that must fire even without the
+   skill installed.
+
+## Toggleable release automation
+
+Set it up; don't leave it optional (reference impl: `ssheleg/task-pipeline`
+`.github/workflows/release.yml`). A `v*`-tag workflow, **off by default**, armed
+per repo by two variables so a fork inherits nothing — `RELEASE_ENABLED` for the
+GitHub release, `PUBLISH_NPMJS` for the registry. It checks tag ↔ manifest
+version, cuts the release from the CHANGELOG section, smoke-tests
+`npx github:<owner>/<repo>#<tag>` from a clean cwd, then publishes with
+provenance (auth per §3 above). That turns steps 2/4/5 into CI; step 6 stays
+manual.
+
+**A release nobody has to attend is the point:** manual publishing is how a
+registry ends up versions behind its own tags with nothing showing the gap — six
+of this family's seven packages, 2026-07-30.