@ssheleg/make-skill 0.7.0 → 0.8.0

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,15 +65,25 @@ 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.
+- `allowed-tools` is a single space-separated **string**, not a YAML list. Claude
+  Code additionally accepts a comma-separated string or a YAML list — write the
+  spec form anyway, since it is the only one every host reads.
 - 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
 
@@ -69,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
 
@@ -79,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` fields
+- `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
@@ -35,6 +50,12 @@ 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.
 
 ## `plugin.json` — `.claude-plugin/plugin.json`
 
@@ -50,7 +71,7 @@ nothing to validate. **`name` is the only required field.**
 | `version` | string | semver. **Set it and you must bump it** — CC uses the version as the cache key, so new commits under an unchanged version never reach users. Omit it entirely and the git SHA is the version (every commit ships) |
 | `description`, `author{name,email,url}`, `homepage`, `repository`, `license`, `keywords[]` | | metadata |
 | `defaultEnabled` | boolean | `false` = installs disabled until the user opts in (CC ≥ 2.1.154). The marketplace entry's copy wins over this one; an existing `enabledPlugins` entry wins over both |
-| `skills` | string\|array | extra skill dirs — **adds to** the default `skills/` scan |
+| `skills` | string\|array | extra skill dirs — **adds to** the default `skills/` scan. One exception: in a marketplace entry whose `source` resolves to the marketplace ROOT, the listed subdirectories REPLACE that scan (if none of them exist, the default scan runs after all) |
 | `commands`, `agents`, `workflows`, `outputStyles` | string\|array | **replace** the default folder. To keep it, list it: `["./commands/", "./extras/"]` |
 | `hooks`, `mcpServers`, `lspServers` | string\|array\|object | path(s) or inline config; own merge rules |
 | `experimental.themes`, `experimental.monitors` | string\|array | still moving; top level warns today, will be required under `experimental` |
@@ -106,7 +127,7 @@ marketplace-only `source`, `category`, `tags`, `strict`, `relevance`,
 | `github` | `{"source":"github","repo":"owner/repo","ref?":"main","sha?":"…"}` |
 | `url` | `{"source":"url","url":"https://…​.git","ref?":…,"sha?":…}` |
 | `git-subdir` | `{"source":"git-subdir","url":"…","path":"packages/x","ref?":…,"sha?":…}` — sparse clone |
-| `npm` | `{"source":"npm","package":"@scope/pkg","version?":…,"registry?":…}` — version resolves to `unknown`, so no update detection |
+| `npm` | `{"source":"npm","package":"@scope/pkg","version?":…,"registry?":…}` — no git SHA to fall back on, so set `version` in the manifest or the entry, else it resolves to `unknown` and updates never fire |
 
 `sha` beats `ref` when both are set. **Marketplace source ≠ plugin source**: the
 first says where `marketplace.json` lives (supports `ref` only), the second where
@@ -133,12 +154,17 @@ Version resolution order: `plugin.json` → marketplace entry → git SHA →
 | MCP | `.mcp.json` |
 | LSP | `.lsp.json` |
 | monitors | `monitors/monitors.json` |
+| themes | `themes/*.json` — `base` preset + sparse `overrides` |
 | executables | `bin/` — on the Bash tool's PATH while enabled |
 | defaults | `settings.json` (only `agent` and `subagentStatusLine` keys) |
 
-**Only `plugin.json` goes inside `.claude-plugin/`.** Every component directory
-sits at the plugin root; components buried in `.claude-plugin/` load as nothing
-and the plugin still "works", which is why this one costs an afternoon.
+**Only `plugin.json` goes inside `.claude-plugin/`.** Those are the DEFAULT
+locations, all at the plugin root — a manifest path field may point anywhere
+else inside the plugin (`"commands": ["./specialized/deploy.md"]`), and from
+2.1.140 Claude Code warns in `claude plugin list` when a manifest key leaves a
+default folder unscanned. What never works is burying components in
+`.claude-plugin/`: they load as nothing while the plugin still "works", which is
+why that one costs an afternoon.
 
 A plugin-root `CLAUDE.md` is **not** loaded as context. Ship instructions as a
 skill.
@@ -151,7 +177,11 @@ string that changes on every update.
 ## Skill frontmatter — host extensions
 
 Portable floor (`name`, `description`, `license`, `compatibility`, `metadata`,
-`allowed-tools`) is in `references/agent-skills-spec.md`. Claude Code also reads:
+`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:
 
 | Field | Effect |
 |---|---|
@@ -194,6 +224,39 @@ there.
   hook's `server` takes `plugin:<plugin>:<server>`. A matcher on the bare server
   key never fires.
 
+## LSP servers and monitors
+
+The load condition above promises both; here is the whole of each.
+
+**LSP** — `.lsp.json` at the plugin root, or `lspServers` inline. Required per
+server: `command` (binary must be on PATH — the plugin does NOT ship it) and
+`extensionToLanguage`. Optional: `args`, `transport` (`stdio` default or
+`socket`), `env`, `initializationOptions`, `settings`, `workspaceFolder`,
+`startupTimeout`, `shutdownTimeout`, `restartOnCrash` (default `true`),
+`maxRestarts`, `diagnostics` (default `true`). `restartOnCrash` and
+`shutdownTimeout` need CC ≥ 2.1.205 — before that, setting either made Claude
+Code skip the server silently, visible only under `claude --debug`. When two
+enabled servers claim the same extension, the first registered wins and the
+other never starts; an invalid server is skipped and no longer blocks a valid
+one (also 2.1.205).
+
+```json
+{ "go": { "command": "gopls", "args": ["serve"],
+          "extensionToLanguage": { ".go": "go" } } }
+```
+
+**Monitors** — `monitors/monitors.json`, or `experimental.monitors` inline (a
+path string there loads from a custom location). Array of `{name, command,
+description, when?}`; `when` is `"always"` (default) or
+`"on-skill-invoke:<skill>"`. Each runs as a background process for the session
+and every stdout line reaches Claude as a notification. Interactive CLI only,
+unsandboxed at hook trust level, skipped where the Monitor tool is unavailable,
+and never loaded from a project-scope `@skills-dir` plugin. `${CLAUDE_PLUGIN_ROOT}`,
+`${CLAUDE_PLUGIN_DATA}`, `${CLAUDE_PROJECT_DIR}` and `${ENV_VAR}` substitute;
+`${user_config.*}` is rejected outright (it would reach a shell), and monitor
+processes get no `CLAUDE_PLUGIN_OPTION_*` either — read the value from a config
+file. Disabling a plugin mid-session does not stop a running monitor.
+
 ## Path variables
 
 | Variable | Resolves to |
@@ -248,7 +311,7 @@ need `/reload-plugins`. Disable with `claude plugin disable <name>@skills-dir`.
 | `claude plugin validate <path> [--strict]` | the conformance gate, offline |
 | `claude plugin init <name> [--with …]` | scaffold a `@skills-dir` plugin |
 | `claude plugin install <name>@<marketplace> [-s user\|project\|local] [--config k=v]` | install |
-| `claude plugin update <name>@<marketplace>` | update — the **full `name@marketplace` form is mandatory** |
+| `claude plugin update <name>@<marketplace>` | update. Docs accept a bare `<name>`; **2.1.212 does not** — `claude plugin update make-skill` answers `Plugin "make-skill" not found`, exits 0, changes nothing. Always pass `name@marketplace` |
 | `claude plugin enable\|disable <name>@<marketplace>` | toggle without uninstalling |
 | `claude plugin uninstall <name>@<marketplace> [--keep-data] [--prune]` | remove (deletes the data dir unless `--keep-data`) |
 | `claude plugin list [--json]` | installed plugins, versions, source, state |