@erclx/canon 5.41.0 → 5.43.0

package/claude/skills/create-rule/references/checklist.md

@@ -0,0 +1,26 @@
+---
+title: Rule bullet checklist
+description: Criteria a session runs over each bullet of a rule it just wrote or revised, and the verdict shape it returns
+---
+
+# Rule bullet checklist
+
+A session reads this after writing or revising a rule, once the body holds its bullets. `rule.md` sets the shape before writing, and this list judges each bullet after.
+
+For each bullet in the rule under audit, return `✅ keep`, `⚠️ revise`, or `❌ drop` with a one-line reason.
+
+## Criteria
+
+1. **Concrete enough to verify.** A reviewer can read a line of code and say whether it complies. "Prefer `pathlib.Path` over `os.path`" passes, since it names both sides.
+2. **Catches a real footgun or a project convention.** A violation produces a bug class, such as blocking I/O in async, or departs from a convention the content test admits. Drop it otherwise.
+3. **Not redundant with the toolchain.** Skip anything the project's formatter, linter, type checker, or spell checker already enforces. Rules cover what tools cannot.
+4. **Uncontested.** When the community is split, drop the bullet or pick a side with a short reason tied to the stack.
+5. **Inside the shape.** At most 200 characters and 2 sentences, one directive plus at most one exception, condition, or short reason, per `## Shape` in `rule.md`.
+6. **Passes the content test.** Claude could not guess it, and it is not a standard convention or information that changes often, per `## Content` in `rule.md`.
+7. **Frontmatter integrity.** `description` names one concern in one line, and a path-scoped rule carries one `paths:` entry per glob.
+8. **Retired keys and names.** An always-on rule omits `paths:`, and no rule carries `globs:`, `alwaysApply:`, or `priority:`. The basename names no folder.
+9. **Template precedent.** H1 and H2 in sentence case and imperative bullets, matching `## Body` in `rule.md`.
+
+## Output shape
+
+Group findings by file. Lead each file block with the per-file verdict count.

package/claude/skills/create-rule/references/rule.md

@@ -1,6 +1,6 @@
 ---
 title: Governance rule reference
-description: Rule frontmatter, body shape, and voice for .claude/rules files
+description: Rule frontmatter, shape limits, content test, sources, body shape, and voice for .claude/rules files
 ---
 
 # Governance rule reference
@@ -9,7 +9,10 @@ description: Rule frontmatter, body shape, and voice for .claude/rules files
 
 - [Overview](#overview)
 - [Scope](#scope)
+- [Shape](#shape)
+- [Content](#content)
 - [Whether a skill belongs behind the rule](#whether-a-skill-belongs-behind-the-rule)
+- [Sources](#sources)
 - [Location](#location)
 - [Names](#names)
 - [Frontmatter](#frontmatter)
@@ -18,29 +21,84 @@ description: Rule frontmatter, body shape, and voice for .claude/rules files
 
 ## Overview
 
-Rules give Claude Code coding constraints scoped to file paths. Claude Code discovers `.claude/rules/**/*.md` at session start.
+Rules give Claude Code coding constraints scoped to file paths. Claude Code discovers `.claude/rules/**/*.md` at session start, and a rule in `~/.claude/rules/` applies to every project on the machine.
 
 A rule with no `paths:` field always applies, at the same priority as `CLAUDE.md`. A rule with `paths:` applies when Claude reads or writes a file matching the glob. Author one rule per topic so the scope stays precise.
 
-A rule with `paths:` loads on a read or a write of a matching file, inside a linked worktree as in the main one. A session creating the first matching file gets the rule only after that write lands, so a rule meant to shape new files also belongs in the skill or the always-on rule a session reads before it writes. Revisit when Claude Code loads a path-scoped rule before a write to a matching path. Re-measure with two headless `claude -p` runs in a linked worktree, one reading a matching file and one reading a file that does not match, each asking whether the rule's content is in context.
+### When a path-scoped rule loads
+
+A rule with `paths:` loads on a read or a write of a matching file, inside a linked worktree as in the main one. A session creating the first matching file gets the rule only after that write lands.
+
+- The first write's floor therefore belongs to the skill that creates the file, per `## Whether a skill belongs behind the rule`
+- Measured again on Claude Code 2.1.302, when the rule attached after the first write to a new file and before the second
+- Revisit when Claude Code loads a path-scoped rule before a write to a matching path
+- Re-measure with two headless `claude -p` runs, one writing a new matching file and one reading a matching file first, each read for when the rule attached
 
 ## Scope
 
-Governs governance rules under `.claude/rules/`: their location, names, frontmatter, and body shape.
+Governs governance rules under `.claude/rules/`, being their shape, content, sources, location, names, frontmatter, and body.
 
 Does not govern:
 
 - Authoring conventions for a document type, which are standards rather than rules. A rule points at the standard that owns one and never restates it.
 - Skill folders and skill frontmatter: `skill.md`
 - Cross-domain behavior rules, which live in `CLAUDE.md` at the project root
+- Judging each bullet after writing, which is `checklist.md`
+
+## Shape
+
+Every limit is a count a reviewer can take, so a rule passes or fails it without judgment.
+
+| Limit                | Value                                                           |
+| -------------------- | --------------------------------------------------------------- |
+| Words in the body    | 300                                                             |
+| Bullets per file     | 15                                                              |
+| H2s per file         | 6                                                               |
+| Bullets per H2       | 7                                                               |
+| Bullet length        | 200 characters                                                  |
+| Sentences per bullet | 2, one directive plus one exception, condition, or short reason |
+
+- Name one concern in `description`. A rule needing a seventh H2 holds two concerns and splits into two files.
+- Keep a reason to the why of its directive, never a paragraph of background
+
+## Content
+
+A bullet loads on every matching edit, so it earns its place only when removing it would cause a mistake.
+
+| Put in a rule                              | Leave out                                                |
+| ------------------------------------------ | -------------------------------------------------------- |
+| What Claude cannot guess                   | Standard language conventions Claude already knows       |
+| A convention that differs from the default | Anything the linter, formatter, or type checker enforces |
+| A footgun that ships silently              | Information that changes often                           |
+
+- Write every bullet concrete enough to verify against a line of code. "Prefer `pathlib.Path` over `os.path`" passes, since it names both sides.
+- Pair a ban with the alternative to take, unless the ban or a neighbor bullet already names it
+- Use no emphasis words such as "CRITICAL" or "You MUST", which newer models overtrigger on
 
 ## Whether a skill belongs behind the rule
 
-A rule fires on a path match with no decision from the session, which is what makes it a floor. Every bullet is one directive and nothing else, so an invariant needing procedure, worked cases, or a branch on project state has no room in the body.
+A rule fires on a path match with no decision from the session, which is what makes it a floor. Procedure, worked cases, and a branch on project state have no room in its bullets, so they belong to a skill.
+
+Each invariant has one copy, in either the rule or the skill. `skill.md` carries the same test for a session arriving from the other side.
+
+- A skill that creates the file the rule globs owns the floor, since the rule loads only after the first write. The rule keeps the edit-time bullets and a pointer.
+- A skill that edits existing files points at the rule, and the rule owns the floor
+- A pointer bullet earns its load only when the skill's description does not already fire on the same edit
+- Keep at most five directives beside a pointer
+- A rule that grows a procedure has become a skill body wearing rule frontmatter
 
-Run the two-part test in reverse before calling the rule finished. The rule already holds what fires on a path edit and ships silently when violated. Ask what a session still needs past the directive, and give that to a skill the rule points at, because a rule that grows a procedure has become a skill body wearing rule frontmatter.
+### Checking the installed skills
 
-Write both when both apply. A rule stating the directive and a skill stating how to carry it out are one invariant at two depths rather than two copies of it, and `skill.md` carries the same checkpoint for a session arriving from the other side. Nothing checks either one.
+Before writing, read the descriptions of the skills in the session's listing and stop at one that names the topic. Point the rule at that skill rather than restating it, and skip the check when the listing holds no skills.
+
+## Sources
+
+A bullet claiming outside practice, such as a language idiom or a library's correct use, rests on a primary source. Unsourced practice drifts, and the bullet goes on loading after it turns wrong.
+
+- Cite the source in the commit that adds the rule, naming a primary page or the bug class the bullet prevents
+- Cut a bullet that has neither a source nor a bug class behind it
+- The toolkit holds its outside-practice rules to a source ledger kept outside the installed tree, so the citation costs no load
+- A bullet resting on how Claude Code behaves ends with a `Revisit when` sentence, per `### Phrasing`
 
 ## Location
 
@@ -56,14 +114,20 @@ A rule's filename is its slug, with no number in front. Nothing orders rules at
 
 - Keep every basename unique across a rule set, internal rules included, since `canon gov` resolves a stack entry and a rename by basename alone.
 - Never name a rule after a subdirectory. A stack entry naming that word expands to the whole folder, so the rule becomes unreachable on its own.
-- A project-authored rule needs its slug free only inside its own subdirectory under `.claude/rules/project/`. A slug the toolkit ships collides with nothing there, since `canon/` and `project/` install side by side.
+- A project-authored rule needs its slug free only inside its own subdirectory under `.claude/rules/project/`, since `canon/` and `project/` install side by side
 
-`canon gov sync` walks only `.claude/rules/canon/`, so `.claude/rules/project/` sits outside the walk by location and is never matched, read, or reported on. A file under `.claude/rules/canon/` itself that no toolkit source names is still reported orphaned, but with no destination offered: the toolkit cannot tell a rule the project dropped there from one it shipped and later renamed, and a destination nested inside `canon/` would be wrong for the first case regardless, since that folder is toolkit-owned and replaced on sync. Nothing is moved either way, since a rule's installed path is one the project's own rules, skills, and docs may cite.
+### What sync reads
+
+`canon gov sync` walks only `.claude/rules/canon/`, so `.claude/rules/project/` is never matched, read, or reported on. A file under `.claude/rules/canon/` that no toolkit source names is reported orphaned, with no destination offered.
+
+- The toolkit cannot tell a rule the project dropped there from one it shipped and later renamed
+- A destination inside `canon/` would be wrong for the first case anyway, since that folder is toolkit-owned and replaced on sync
+- Nothing is moved either way, since the project's own rules, skills, and docs may cite a rule's installed path
 
 ## Frontmatter
 
-- `description` (required): one line naming what the rule enforces and where
-- `paths` (optional): one glob per entry, for a rule scoped to a file set
+- `description` (required): one line naming what the rule enforces and where. It is canon's own field, read by `canon gov list`.
+- `paths` (optional): one glob per entry, for a rule scoped to a file set. It is the only field Claude Code reads.
 - Omit `paths` for an always-on rule that states a global principle with no file scope
 - Do not emit the legacy Cursor keys `globs`, `alwaysApply`, or `priority`. They are not read.
 
@@ -75,47 +139,61 @@ paths:
 ---
 ```
 
+Frontmatter that fails to parse loads the rule as if it had no `paths`, so a broken glob turns a scoped rule always-on. Quote every glob that opens with `*` or `{`.
+
 ## Body
 
 - Open with an H1 `# <Topic> standards` in sentence case, then group rules under H2 sections. Proper nouns keep their casing (`# TypeScript standards`, `# Next.js standards`).
 - Use imperative voice for every rule (`Prefix booleans with is`, not `Booleans should be prefixed`)
 - State one rule per bullet as a single directive line
-- State what to do and what not to do. Do not explain the reasoning behind a rule.
+- State what to do and what not to do. Add one short reason when the why is not obvious, inside the limits in `## Shape`.
 
 ### Phrasing
 
-- End the directive line of a ban asserting how the model or a tool behaves with one `Revisit when <finding>.` sentence, which states a condition rather than the reasoning. A style, safety, or consistency ban takes none.
+A ban asserting how the model or a tool behaves ends its directive line with one `Revisit when <finding>.` sentence, which states a condition rather than the reasoning. A style, safety, or consistency ban takes none.
+
 - Phrase a rule as a ban on the forbidden shape when it could otherwise enumerate allowed options, so it stays stable as categories grow
 - Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
 
 ### Scope of a rule file
 
+A rule file holds one topic in its current shape.
+
 - Keep the file to one topic. A second topic is a second rule file.
 - Do not restate a rule that a sibling rule or `CLAUDE.md` already owns. Point once, never duplicate.
-- Name the current layout only, in a glob and in the body alike. A layout change ships a migration verb, as `canon migrate surface-roots` and `canon migrate records` did, rather than a rule line or a glob that keeps the old spelling loading.
+- Name the current layout only, in a glob and in the body alike
+- A layout change ships a migration verb, such as `canon migrate records`, rather than a line or a glob that keeps the old spelling loading
 
 ## Examples
 
 ### Correct
 
+A scoped description, a `paths` list, and one directive per bullet, one of them carrying a short reason.
+
 ```markdown
 ---
-description: Enforce naming conventions for functions, booleans, and collections
+description: Enforce migrations, bound queries, and transaction ownership for persistence code
 paths:
   - '**/*.ts'
 ---
 
-# Naming standards
+# Persistence standards
 
-## Semantics
+## Schema changes
 
-- Prefix booleans with `is`, `has`, `should`, or `can`
-- Name functions as actions describing what they do
-- Name collections as plurals and items as singulars
+- Express every schema change as a migration file committed to version control.
+- Never edit a migration that has run in a shared environment. Add a new one.
+
+## Query construction
+
+- Pass every runtime value as a bound parameter.
+- Map a table name or sort direction through an allow-list, since neither can be bound.
 ```
 
 ### Incorrect
 
+A vague description, legacy Cursor keys, and a paragraph of reasoning in place of directives.
+
 ```markdown
 ---
 description: Naming

package/claude/skills/create-skill/SKILL.md

@@ -13,6 +13,7 @@ Read these files in parallel:
 - `${CLAUDE_SKILL_DIR}/references/skill-requirement.md`: what `REQUIREMENT.md` must answer, its sections, and its template
 - `${CLAUDE_SKILL_DIR}/references/skill-paths.md`: which root a path in the body resolves against, and how the body cites another skill's reference
 - `${CLAUDE_SKILL_DIR}/references/skill-disclosure.md`: where each reference is named, the contents block, the trigger and guard that stay in the body, and what moves to `references/`
+- `${CLAUDE_SKILL_DIR}/references/skill-frontmatter.md`: the frontmatter fields, their limits, and which keys an upload accepts
 
 ### Writing standards
 

package/claude/skills/create-skill/references/skill-disclosure.md

@@ -5,22 +5,30 @@ description: Keeping a skill body and its references under the ceiling, what mov
 
 # Skill disclosure reference
 
+Checked against the [skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) page on `2026-10-18`.
+
 Applies to the size and split of every `SKILL.md` and every file under a skill's `references/`.
 
 ## Rules
 
 - Keep `SKILL.md` and each file under `references/` at or under the 300 rendered line ceiling `markdown.md` sets for a whole document. The ceiling binds procedure as much as reference material.
+- Treat the 300 as canon's own choice, stricter than the 500 lines Anthropic sets for a `SKILL.md`.
 - Look at a body once it passes 150 lines. That number prompts a look and gates nothing.
 - Move a catalog, a table of cases, or a format spec running past roughly 15 lines to `references/` at any body length.
 - Below the ceiling, name the branch that skips a block before moving it. A block every run dereferences costs a read and saves nothing.
 
 ### Moving a step
 
-- Past the ceiling, move a whole step to a reference, preferring a step a named branch skips. Keep the step heading in the body with one line naming the file to read on reaching it, so the body still shows every step in order.
-- Name every file under `references/` in the body at the point a session reads it, since an unnamed reference is never loaded.
+Past the ceiling, move a whole step to a reference, preferring a step a named branch skips.
+
+- Keep the step heading in the body with one line naming the file to read on reaching it, so the body still shows every step in order
+- Name every file under `references/` in the body at the point a session reads it, since an unnamed reference is never loaded
 
 ### Contents, triggers, and citations
 
+A reference is read from the top, and only when the body sends a session to it.
+
 - Open a file under `references/` running over 100 lines with a `## Contents` H2 of anchor links after its H1 and intro, so a session that reads only the top of the file still sees everything it holds.
 - Keep the trigger, the skip condition, and the guard in the body. A run that never reaches the block has to decide that without opening the reference.
+- Keep references one level deep from `SKILL.md`. A file linked from a reference gets a partial read.
 - Point one skill at a sibling skill's reference by the form `skill-paths.md` states, `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`, and name the owner rather than copying the file.

package/claude/skills/create-skill/references/skill-frontmatter.md

@@ -0,0 +1,43 @@
+---
+title: Skill frontmatter reference
+description: The frontmatter fields a skill carries, their limits, and which keys a claude.ai upload accepts
+---
+
+# Skill frontmatter reference
+
+Checked against the [Claude Code skills](https://code.claude.com/docs/en/skills) and [skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) pages on `2026-10-18`.
+
+## Fields
+
+- **`name`** (required): kebab-case, matches folder name, no spaces or capitals, and at most 64 characters
+- **Reserved words**: an upload to claude.ai or the API rejects `anthropic` and `claude` in a name, and Claude Code does not.
+- **`description`** (required): what it does + when to use it, under 1024 chars, no XML tags. That is the portable maximum.
+- **Listing cap**: Claude Code truncates `description` plus `when_to_use` at 1,536 characters in its skill listing, so put the key use case first.
+- **`disable-model-invocation: true`**: Claude will not auto-trigger, and the `Skill` tool also refuses the operator's request made in words. Set it only on a skill run by slash command alone.
+- **`allowed-tools`**: tools Claude can use without asking permission during the turn that invokes the skill, cleared at the next message. It grants and never limits the tool set.
+- **`metadata`**: optional key-value pairs (`author`, `version`, `mcp-server`)
+- **`metadata.family`** (required under `claude/skills/`): the skill map group, as one key from `families` in `canon claude skills list --json`. A skill under `.claude/skills/` takes none.
+
+Outside Claude Code, only `name`, `description`, `license`, `compatibility`, `metadata`, and `allowed-tools` pass an upload, and any other key is a hard error. Keys nested under `metadata` pass, which is why `family` nests there.
+
+### Optional fields
+
+Claude Code documents more optional fields. The skills page holds the detail, so this table keeps one line each.
+
+| Field                      | Effect                                    |
+| -------------------------- | ----------------------------------------- |
+| `when_to_use`              | Trigger phrases appended to `description` |
+| `argument-hint`            | Autocomplete hint for arguments           |
+| `arguments`                | Named positional arguments                |
+| `user-invocable`           | `false` leaves it to Claude alone         |
+| `disallowed-tools`         | Tools removed while it is active          |
+| `model`, `effort`          | Override both for the turn                |
+| `context`                  | `fork` runs it in a subagent              |
+| `agent`                    | Subagent type for `context: fork`         |
+| `background`               | Whether a fork runs in the background     |
+| `hooks`                    | Hooks registered for the session          |
+| `paths`                    | Globs limiting automatic loading          |
+| `shell`                    | `bash` or `powershell`                    |
+| `license`, `compatibility` | Accepted, never acted on                  |
+
+A skill wanting only the no-auto-trigger effect writes `Do NOT auto-trigger` in its description rather than setting `disable-model-invocation`.

package/claude/skills/create-skill/references/skill-paths.md

@@ -32,20 +32,23 @@ A body failing any of these is non-conforming even when every path resolves in t
 
 Know which root a file lives under before referencing it.
 
-- Bundled skill assets (`references/`, `scripts/`, `assets/`) resolve against the skill's own directory. Reference them with `${CLAUDE_SKILL_DIR}/<path>`, never a bare relative path, which resolves against the session cwd and fails when a plugin skill runs from another project.
+- Bundled skill assets (`references/`, `scripts/`, `assets/`) resolve against the skill's own directory, so reference them with `${CLAUDE_SKILL_DIR}/<path>`
+- Never use a bare relative path for one, which resolves against the session cwd and fails when a plugin skill runs from another project
 - Installed shared docs (`.claude/rules/`, `canon/context/`) resolve against the target project cwd, where install placed them. Reference them by that path.
-- Do not hand-copy another skill's reference into a skill. If a skill must carry its own copy, generate it from the single source and reference it through `${CLAUDE_SKILL_DIR}`, so one owner keeps every copy in sync.
+- Do not hand-copy another skill's reference. A skill that must carry its own copy generates it from the single source and reads it through `${CLAUDE_SKILL_DIR}`.
 
 ## Citing another skill's reference
 
 A reference shared across skills lives in the `references/` of the skill that owns it, so a body cites it by the sibling path.
 
-- Cite another skill's reference as `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`. The plugin ships the skills side by side, so the sibling path resolves in every install. Name the owner skill rather than copying the file.
-- State the path once per body, at the site that reads the reference. A later mention of a reference the body already read stays bare, since repeating the path at every mention is noise rather than instruction.
+- Cite another skill's reference as `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`, naming the owner. The plugin ships the skills side by side, so the sibling path resolves in every install.
+- State the path once per body, at the site that reads the reference. A later mention stays bare, since repeating the path at every mention is noise.
 - A guard on a reference's presence names the file rather than the folder holding it, since a folder test answers for a sibling that happens to be there.
 
 ### Form and ownership
 
+One variable expands reliably, and one owner holds each procedure.
+
 - Use `${CLAUDE_SKILL_DIR}`, never a bare `../../` and never `${CLAUDE_PLUGIN_ROOT}`, since only the first expands before the body reaches the model.
 - Cite a shared procedure, never restate it. A procedure two or more skills execute gets one definition in its owner's reference and a citation in each body.
 - Keep the trigger in the body and the procedure in the reference. The citing skill states when the procedure runs and what it runs against, since that varies per skill and the reference cannot know it.

package/claude/skills/create-skill/references/skill-practice.md

@@ -31,9 +31,11 @@ A practice skill failing any of these is non-conforming even when every heading
 
 ## Closing sections
 
-- Follow every concern group with three H2s in this order: `## Excuses and rebuttals`, `## Red flags`, and `## Before handing over`. A section naming what the skill delegates comes after the three, and nothing else does.
+Follow every concern group with `## Excuses and rebuttals`, `## Red flags`, and `## Before handing over`, in that order. Only a section naming what the skill delegates comes after.
+
 - Spell each heading exactly. An H3, or a heading carrying more words such as `## Red flags that mean start over`, reads as missing.
-- Write `## Excuses and rebuttals` as a two-column table pairing a reason a session gives to skip or shortcut the practice with the answer to it. Never write a row rebutting an objection nobody raised, since that row is ceremony. Revisit when a practice skill's table is observed failing to stop an excuse it names.
+- Write `## Excuses and rebuttals` as a two-column table pairing a reason a session gives to skip or shortcut the practice with the answer to it
+- Never write a row rebutting an objection nobody raised, since that row is ceremony. Revisit when a table is observed failing to stop an excuse it names.
 - Write `## Red flags` as bullets naming signs a session can observe in its own work mid-task, never a restatement of a rule above.
 - Write `## Before handing over` as the exit checklist, each line a check against what the session produced.
 
@@ -47,6 +49,7 @@ A practice skill failing any of these is non-conforming even when every heading
 ## Which skills are practice skills
 
 - `canon claude skills audit` keeps the list of practice skills and checks each listed one for the three closing sections and the ledger.
-- It keeps a wider ledger list beside it, holding every practice skill plus the skills that teach a craft drawn from outside sources without a practice's closing shape. A skill on the wider list alone owes the ledger and none of the three sections.
+- It keeps a wider ledger list beside it, adding the skills that teach a craft drawn from outside sources without a practice's closing shape
+- A skill on the wider list alone owes the ledger and none of the three sections
 - Never mark a skill as a practice skill in its own frontmatter, since a self-declared kind lets a skill exempt itself.
 - Both lists name this toolkit's shipped skills alone, so a project's own practice skill takes this shape with no check behind it.

package/claude/skills/create-skill/references/skill-requirement.md

@@ -29,9 +29,11 @@ A requirement that leaves any of the three open is non-conforming regardless of
 
 ## Purpose
 
-- Treat the file as the compressed statement of what the skill is for. A skill body is procedural by design, so its purpose sits spread across its steps, and a reader gets this file before opening the body whether or not the skill's scope is contested.
+- Treat the file as the compressed statement of what the skill is for. A body is procedural by design, so its purpose sits spread across its steps.
+- A reader gets this file before opening the body, whether or not the skill's scope is contested
 - Read it before editing the skill. When a change closes no gap the requirement states, change the requirement first or drop the change.
-- Write the gaps from what the skill is for, then compare the body against them. A requirement derived from the body records the body's accidents as the requirement, and misinforms a reader who reads it in place of the body.
+- Write the gaps from what the skill is for, then compare the body against them
+- A requirement derived from the body records the body's accidents as the requirement, and misinforms a reader who reads it in place of the body
 
 ## Content
 

package/claude/skills/create-skill/references/skill.md

@@ -5,6 +5,8 @@ description: Skill structure and authoring rules for Claude Code
 
 # Claude skill reference
 
+Checked against the [Claude Code skills](https://code.claude.com/docs/en/skills) and [skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) pages on `2026-10-18`.
+
 ## Contents
 
 - [Overview](#overview)
@@ -26,7 +28,7 @@ Skills give Claude Code domain-specific constraints and rules inline, so it can
 
 ## Scope
 
-Governs a skill folder under `skills/` as one artifact: `SKILL.md`, its siblings `REQUIREMENT.md` and `EVAL.md`, and the bundled reference, script, and asset folders beside them.
+Governs a skill folder under `skills/` as one artifact, being `SKILL.md`, its siblings `REQUIREMENT.md` and `EVAL.md`, and the bundled reference, script, and asset folders beside them.
 
 Does not govern:
 
@@ -37,7 +39,7 @@ Does not govern:
 - **`rule.md`**: path-scoped coding rules, which load on a file match rather than on a request match
 - **the `write-human` skill**: voice, rhythm, and sentence construction in a skill body
 - **`markdown.md`**: punctuation, formatting, and word choice in a skill body
-- **`slug.md`**: the transform from a branch name to a slug a skill carries in a filename
+- **`slug.md`**: the transform from a branch name to a filename slug
 - **the `create-skill` skill and the creation-time bullet in the `skill` governance rule**: whether a new skill earns its place, by the three-question test
 
 ## Changing a skill
@@ -51,11 +53,13 @@ Answer all four before editing, and carry the answers into wherever the change i
 
 ## Whether a rule belongs beside the skill
 
-A skill fires when a session invokes it or its description matches the request. A path-scoped rule fires when a session reads or writes a file matching its glob, with no decision from the session at all. The rule is the floor and the skill is the depth.
+A skill fires when a session invokes it or its description matches the request. A path-scoped rule fires when a session reads or writes a file matching its glob, with no session decision. The rule is the floor and the skill is the depth.
 
-Run the two-part test over what the body states before calling the skill finished. Does the invariant fire when a specific path is edited, and does violating it ship silently? An invariant passing both halves belongs in a rule as well, since a session that never invoked the skill still edits that path. An invariant failing either half stays here, which is most of a body.
+- Run the two-part test over the body before calling the skill done. Does the invariant fire when a specific path is edited, and does violating it ship silently?
+- An invariant passing both halves moves to a rule, since a session that never invoked the skill still edits that path. It stays here when this skill creates the file the rule globs.
+- An invariant failing either half stays here, which is most of a body
 
-Write that rule to the shape `rule.md` sets and leave the procedure here, since the two carry one invariant at two depths rather than two copies of it. Nothing checks the split.
+Write that rule to the shape `rule.md` sets, keeping one copy of each invariant. A skill that only edits existing files points at the rule.
 
 ## Skill types
 
@@ -89,87 +93,102 @@ allowed-tools: <tools required>
 
 ## Structure
 
-- Skill is a folder named in kebab-case containing `SKILL.md` (required), `REQUIREMENT.md` (required), `EVAL.md` (optional), `scripts/` (optional), `references/` (optional), `assets/` (optional)
-- Create a new skill with its `REQUIREMENT.md` beside it, even where nobody contests its scope. A requirement present for some skills and absent for others cannot be scanned, since an absence reads as a gap rather than as a verdict
-- Name a file sitting directly in the skill folder in capitals and a bundled folder in lowercase, so the parts a reader opens are distinct from the ones a skill loads
+A skill is a folder named in kebab-case. It holds `SKILL.md` and `REQUIREMENT.md`, both required, and maybe `EVAL.md`, `scripts/`, `references/`, and `assets/`.
+
+- Create a new skill with its `REQUIREMENT.md` beside it, even where nobody contests its scope, since an absence reads as a gap rather than as a verdict
+- Name a file sitting directly in the skill folder in capitals and a bundled folder in lowercase, so the parts a reader opens differ from the ones a skill loads
 - `EVAL.md` holds prompts and a judging rubric a person runs by hand, since the automated `claude plugin eval` runner is gated in early access
 
 ### Folder and file rules
 
+The loader reads the folder name as the skill name, so the name follows the same casing everywhere.
+
 - `SKILL.md` must start with YAML frontmatter between `---` delimiters
 - No `README.md` inside the skill folder
 - No spaces, capitals, or underscores in folder or skill name
 
 ## Frontmatter
 
-- **`name`** (required): kebab-case, matches folder name, no spaces or capitals
-- **`description`** (required): what it does + when to use it, under 1024 chars, no XML tags
-- **`disable-model-invocation: true`**: Claude will not auto-trigger, and the `Skill` tool also refuses the operator's own request made in words. Set it only on a skill run by slash command alone. A skill wanting just the first effect writes `Do NOT auto-trigger` in its description.
-- **`allowed-tools`**: restrict tool access when the skill is active
-- **`metadata`**: optional key-value pairs (`author`, `version`, `mcp-server`)
-- **`metadata.family`** (required on a skill under `claude/skills/`): the skill map group the skill's row sits under, as one key from `families` in `canon claude skills list --json`. A skill under `.claude/skills/` takes none.
+Read `skill-frontmatter.md` for the required and optional fields, their limits, and which keys an upload accepts.
 
 ## Description
 
 - Structure: `[What it does] + [When to use it] + [Key trigger phrases]`, quoting phrases users would say
 - Be specific, not vague. Claude routes based on this field alone.
-- Add negative triggers if skill is over-triggering: `Do NOT use for X`
+- Write in the third person, since the description is injected into the system prompt. Write "Reviews code" over "I review code".
+- Add negative triggers if skill is over-triggering: `Do NOT use for X`. That form is canon's own, and Anthropic's pages do not mention it.
 
 ## Body
 
 ### Rule content and scope
 
+A body holds behavioral rules and pointers to reference docs, front-loading the critical ones. Narrative about what files are or how the system works belongs in `docs/`.
+
 - Use imperative voice throughout, and sentence case for every heading
-- Front-load critical instructions
-- Contain only behavioral rules (what to do, what not to do) and pointers to reference docs. Narrative descriptions of what files are or how the system works belong in `docs/`, not in the skill body.
-- State rules, not inventories. Reference docs for lists that change, and phrase a rule as a ban on the forbidden shape rather than an enumeration of allowed options, so it stays stable as categories change.
+- State rules, not inventories. Reference docs for lists that change.
+- Phrase a rule as a ban on the forbidden shape rather than an enumeration of allowed options, so it stays stable as categories change
+- When referencing project files, include "from the project root" in the read instruction
+- Run independent operations, such as file reads and shell commands, in parallel to reduce latency
 
-#### Current rule and grouping
+### Current rule and grouping
+
+State the current rule only, in the body and in every file under `references/`. The incident and the date that earned a rule go in `REQUIREMENT.md` under `Gap`, or stay in git, and a date inside a fence or a code span is example data and stays.
 
 - Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
-- State the current rule only, in the body and in every file under `references/`. The incident and the date that earned a rule go in `REQUIREMENT.md` under `Gap`, or stay in git. A date inside a fence or a code span is example data and stays.
-- Group bullets under H2 headings by domain concern. Keep dos and don'ts together under the topic they belong to rather than splitting them into flat rules and constraints sections.
+- Group bullets under H2 headings by concern, keeping dos and don'ts together rather than in flat rules and constraints sections
 - One actionable constraint per bullet. Prefer the `X over Y` form for preferences.
 
-#### Examples and density
+### Examples and density
+
+Every statement in a body costs a read on each invocation.
 
-- Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer.
-- Keep a statement only when removing it would change what the agent does, naming a principle as a few-word handle rather than explaining it. Revisit when a run shows the model ignoring a principle named only as a handle.
+- Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer
+- Keep a statement only when removing it would change what the agent does, naming a principle as a few-word handle rather than explaining it
+- Revisit when a run shows the model ignoring a principle named only as a handle
 
 ### Progressive disclosure
 
 Keeping a body and its references under the ceiling, what moves to `references/` and what stays, and how a body names a reference are in `skill-disclosure.md`.
 
-### Reading and running commands
-
-- When referencing project files, include "from the project root" in the read instruction
-- When executing multiple independent operations (file reads, shell commands), run them in parallel to reduce latency
-
 ### Anti-patterns to avoid
 
-- Avoid flags that dispatch between alternate flows. The model misreads them and runs the vanilla path. Dry-run-style toggles are fine. For alternate flows, prefer a separate skill or manual invocation of two skills in sequence.
+Avoid flags that dispatch between alternate flows, since the model misreads them and runs the vanilla path. Dry-run-style toggles are fine, and an alternate flow takes a separate skill or two skills invoked in sequence.
+
 - When a skill should fire from multiple callers, rely on description matching with strong trigger phrases. Do not hardcode `Skill` calls in sibling skills that could trigger it naturally.
-- Before collapsing a manual multi-step flow into a skill, ask what the manual pauses do. Where a pause carries external timing, error-surfacing, or judgment weight, prefer explicit per-step confirmation.
+- Before collapsing a manual multi-step flow into a skill, ask what the manual pauses do
+- Where a pause carries external timing, error-surfacing, or judgment weight, prefer explicit per-step confirmation
+
+### Output paths
+
+A success line emits the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted, since a bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so the body states which path and leaves the form to that section.
+
+### Where output lands
+
+Before writing, decide whether the output is a deliverable, which lands among the project's tracked files, or a session record. A session record lands under `.canon/` in the named subfolder for its kind, never in a folder the body invents.
 
-### Output and tuning
+- Kinds: `tasks/`, `plans/`, `review/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, `teach/`, `ready/`, `feedback/`, `picks/`, `evidence/`, `transcripts/`, `walkthroughs/`
+- `tmp/` takes scratch nothing else claims
+- A `review/` writer names its file `<kind>-<slug>.md` and writes it flat
+- An `evidence/` folder takes the next two-digit ordinal as `<nn>-<slug>/`, numbered in the order the folders first appeared
 
-- Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. A bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so a skill body states which path is emitted and leaves the form to that section.
-- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, `teach/`, `ready/`, `feedback/`, `picks/`, `evidence/`, `transcripts/`, or `walkthroughs/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. A `review/` writer names its file `<kind>-<slug>.md` and writes it flat, and an `evidence/` folder takes the next two-digit ordinal as `<nn>-<slug>/`, numbered in the order the folders first appeared.
-- Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
-- When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
-- Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions, never turning a soft cap hard for aesthetic drift.
+### Templates, input, and tuning
+
+Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
+
+- When a skill gathers input or pre-seeds a template, attach a proposed default derived from project context to every question. Accept "use defaults" as a bulk-confirm.
+- Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill
+- Tighten only on correctness regressions, never turning a soft cap hard for aesthetic drift
 
 ## Scripts
 
-- Use `scripts/` for operations that must be deterministic or repetitive
-- Ask whether a CLI verb the project already has does the job before writing a script. A verb is already installed and tested, and a script beside it is a second copy that drifts
-- Write a script in TypeScript and run it as `bun ${CLAUDE_SKILL_DIR}/scripts/<name>.ts`. Keep bash for a few lines that start one command. The rule governs a new script, so bash kept by decision is no breach and is not ported unasked, such as `review-ui`'s `scripts/pw.sh` as glue and the shell scripts the web tooling stacks ship, whose port was deferred
-- Import no package. A plugin loads from a cache that carries no `node_modules`, so only `node:` built-ins and the CLIs the skill already requires resolve
-- Use XML tags in script output for reliable parsing: `<SECTION>content</SECTION>`
+Use `scripts/` for operations that must be deterministic or repetitive. First ask whether a CLI verb the project already has does the job, since a verb is installed and tested and a script beside it is a second copy that drifts.
 
-### Inline commands
+- Write a script in TypeScript and run it as `bun ${CLAUDE_SKILL_DIR}/scripts/<name>.ts`. Keep bash for a few lines that start one command.
+- Import no package. A plugin loads from a cache that carries no `node_modules`, so only `node:` built-ins and the CLIs the skill already requires resolve.
+- Use XML tags in script output for parsing: `<SECTION>content</SECTION>`
+- Guard a git or shell command a body runs inline with `2>/dev/null || echo "FALLBACK"`. A TypeScript script uses try and catch instead.
 
-- Always include `2>/dev/null || echo "FALLBACK"` guards on git and shell commands a skill body runs inline. A TypeScript script handles failure with try and catch instead
+The TypeScript rule governs a new script, so bash kept by decision is no breach and is not ported unasked. Examples are `review-ui`'s `scripts/pw.sh` as glue and the shell scripts the web tooling stacks ship, whose port was deferred.
 
 ## Invocation
 
@@ -180,10 +199,14 @@ Keeping a body and its references under the ceiling, what moves to `references/`
 
 ### Correct
 
+Each line names its reason after the `#`.
+
 - `description: Reviews code for bugs and clarity. Use when asked to "review this" or "check the PR".` # names the action, then the trigger phrases
 - `Read ${CLAUDE_SKILL_DIR}/references/post.md on reaching this step.` # a moved step keeps its heading and one load line
 
 ### Incorrect
 
+Each line names its fault after the `#`.
+
 - `description: Handles all code tasks in scripts/, src/, and lib/, and any file ending in .ts .js .py .sh.` # path-focused and keyword-stuffed
 - `A good review checks bugs, performance, security, style, naming, coverage, docs, and SOLID...` # dumps everything inline instead of citing a standard

package/claude/skills/decision-escalate/SKILL.md

@@ -70,8 +70,7 @@ Restate each pick in one line, then continue the work.
 
 A pick that changes a written artifact goes into it under the rule its own standard sets, and a pick that settles nothing written stays in the session.
 
-- An answer to an open plan question rewrites its `- Suggested:` line to the pick, naming the operator as source, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`
-- Leave the `- Answer:` slot blank, since the standard bars a session from filling it, and the blank resolves to the rewritten suggestion
+- Record an answer to an open plan question per `### Overrides and settled questions` in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`
 
 Output after the answers land: