@erclx/canon 5.40.0 → 5.42.0

package/claude/skills/context-fold/references/context-refresh.md

@@ -5,19 +5,26 @@ description: How context-fold Step 3 folds diff-scoped rewrites into canon/conte
 
 # Refresh context entries
 
-Step 3 of `context-fold`, reached in order once `canon/context/index.md` lists at least one entry.
-
-The diff carries what the repository changed, and this step rewrites against it.
+Step 3 of `context-fold`, reached in order once `canon/context/index.md` lists at least one entry. The diff carries what the repository changed, and this step rewrites against it.
 
 When the baseline is unusable, scope this step to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the context refresh.`
 
-Reuse the diff from the baseline above, names and content both. For each domain listed in `canon/context/index.md`, read its own entry: a flat `canon/context/<domain>.md`, or, for a domain split into a folder, its `canon/context/<domain>/index.md` and every sibling file that index links. Follow the index rather than globbing the folder, since a folder can hold a file the index does not list yet.
+## Reading each entry
+
+Reuse the diff from the baseline above, names and content both. For each domain listed in `canon/context/index.md`, read its own entry, following the index rather than globbing the folder, since a folder can hold a file the index does not list yet.
+
+- A flat domain reads `canon/context/<domain>.md`
+- A domain split into a folder reads its `canon/context/<domain>/index.md` and every sibling file that index links
+
+### What to rewrite
+
+An entry is relevant only when the diff touches what it states, and the rewrite stays inside the part the trigger names.
 
 - Treat an entry as relevant only when the diff adds, moves, or removes a folder its Layout lists, makes a folder's bullet untrue, or changes a trap it names
 - For each relevant entry, rewrite only the H3 or the gotcha the trigger names, and leave unrelated sections alone
 - Never rewrite a split domain's own `index.md`, which a regen overwrites, and rewrite the sibling file the section lives in instead
 - Edit the bullet that went untrue in place and never append one beside it, the same rule the body states.
-- Write a reference to another entry as the path that entry sits at, rather than as its bare filename. `${CLAUDE_SKILL_DIR}/references/context.md` states the form, and a bare name strands the reference once a domain splits into subfolders.
+- Write a reference to another entry as the path that entry sits at, per `${CLAUDE_SKILL_DIR}/references/context.md`, since a bare filename strands it once a domain splits into subfolders
 
 ## When the diff removes a capability
 
@@ -25,15 +32,25 @@ The mapping above is scoped by file, and a removal invalidates claims that mappi
 
 Grep the tree for the name that went, rather than for the paths the diff carries. A capability removed by name is cited by that name, which reaches a file the diff never touched.
 
-- An entry this run already rewrote is read whole before it is left. A refresh that updates the top and leaves a contradicting claim below reads worse than an untouched entry, because the current opening lends authority to the stale remainder. This is the one case that overrides "do not touch unrelated sections", and it overrides it only inside an entry the run edited anyway.
-- A claim comparing two surfaces is checked even where its file is outside the diff. Such a claim holds only while both surfaces do, so moving one inverts it with nobody editing the file it sits in.
+- Read an entry this run rewrote whole before leaving it. An updated top over a contradicting claim below reads worse than an untouched entry, since the opening lends authority to the stale rest.
+- That is the one case overriding "do not touch unrelated sections", and only inside an entry the run edited anyway
+- Check a claim comparing two surfaces even where its file is outside the diff. It holds only while both surfaces do, so moving one inverts it with nobody editing its file.
 
 Report each hit as an ordinary rewrite.
 
-Create a new entry only for a domain `canon/context/index.md` already lists but carries no file for, following `${CLAUDE_SKILL_DIR}/references/context.md` for its shape. Before treating a domain as carrying no file, confirm it holds no entry under either spelling, `canon/context/<domain>.md` or `canon/context/<domain>/index.md`, since a domain already split into a folder still passes a check that only looked for the flat file. A row in the catalog is the deliberate decision, taken by whoever added it. This step only fills in what that decision left open, and only until the next `canon indexes regen` pass, which rebuilds the catalog from each entry's own frontmatter plus every sibling's and drops a row whose file still does not exist. Create the file before that regen runs, or the row this bar exists to fill in is gone. A domain the catalog does not list at all is a different case: report it and stop, rather than creating an entry or a catalog row for it.
+## Creating an entry
+
+Create a new entry only for a domain `canon/context/index.md` already lists but carries no file for, following `${CLAUDE_SKILL_DIR}/references/context.md` for its shape. A row in the catalog is the deliberate decision, taken by whoever added it, and this step only fills in what that decision left open.
+
+- Confirm the domain holds no entry under either spelling, `canon/context/<domain>.md` or `canon/context/<domain>/index.md`, since a split domain passes a check for the flat file alone
+- The next `canon indexes regen` rebuilds the catalog from each entry's frontmatter plus every sibling's, dropping a row whose file does not exist. Create the file before it runs.
+- A domain the catalog does not list at all is a different case. Report it and stop, rather than creating an entry or a catalog row for it.
+
+## Writing and reporting
 
 Write each updated entry immediately. Output one line per file, naming the path this run actually wrote rather than always the flat template:
 
-`✅ Context: canon/context/<domain>.md` for a flat entry, or `✅ Context: canon/context/<domain>/<sub-area>.md` for the sibling file a nested edit landed in
+- `✅ Context: canon/context/<domain>.md` for a flat entry
+- `✅ Context: canon/context/<domain>/<sub-area>.md` for the sibling file a nested edit landed in
 
 The base lint-staged config runs `canon indexes regen` on every committed `*.md`, so `canon/context/index.md` refreshes automatically on commit. No manual step needed.

package/claude/skills/context-fold/references/unusable-baseline.md

@@ -14,8 +14,10 @@ The baseline is unusable in two cases:
 
 An unusable baseline costs only the committed half. `git diff <base> HEAD` is empty by definition once the base equals HEAD, while `git diff HEAD` and `git ls-files --others --exclude-standard` still report uncommitted and untracked work at correct scope.
 
-**Step 3 keeps the scoped set.** Run it on the working tree and untracked files alone, and skip only when that set comes out empty, reporting the warning its own reference names.
+## Step 3 keeps the scoped set
 
-Never substitute the whole tree for a missing baseline, and do not widen to `git log -p -1` for coverage. On a fresh `git init` project the last commit is the scaffold commit, so that read is the whole tree by another route, and Step 3 writes, so the same set rewrites every context entry that tree touches. `task-complete` takes the widened read for its marking step, which only reads and matches conservatively against outcomes already on the board.
+Run Step 3 on the working tree and untracked files alone, and skip only when that set comes out empty, reporting the warning its own reference names. Widening what a step reads is safe, and widening what a step writes is not.
 
-Widening what a step reads is safe. Widening what a step writes is not.
+- Never substitute the whole tree for a missing baseline, and do not widen to `git log -p -1` for coverage
+- On a fresh `git init` project the last commit is the scaffold, so that read is the whole tree by another route. Step 3 writes, so it would rewrite every context entry that tree touches.
+- `task-complete` takes the widened read for its marking step, which only reads and matches conservatively against outcomes already on the board

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

@@ -18,6 +18,11 @@ The subdir gets picked by feel, so a UI copy rule lands in the always-on folder
 - Write under `.claude/rules/project/`, the subfolder the sync engine reads as project-authored by location
 - Take a slug no rule in the chosen project subdir uses and that equals no subdir name
 - Read the rule standard before writing the body
+- Hold the body to the rule standard's shape limits on words, bullets, sections, and bullet length
+- Apply the content test, leaving out what Claude already knows, what the toolchain enforces, and what changes often
+- Check the installed skills for one already covering the topic and point the rule at it, skipping the check when none are listed
+- Run every written bullet through the checklist and fix what fails before reporting
+- Tell the user to cite a source in the commit that adds a rule claiming outside practice
 - Emit the path scope for a path-scoped rule and omit the key entirely for an always-on one
 - Preview the resolved path, subdir, slug, and frontmatter, then write without pausing
 - Say when the rule loads, since path-scoped and always-on rules behave differently

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

@@ -22,6 +22,7 @@ Resolve both from the request, and ask only for what is missing. Attach a propos
 
 - What the rule enforces: one topic, phrased as a standard (`<topic> conventions`).
 - Scope: a path glob relative to the project root (`<dir>/**/*.<ext>`) for a path-scoped rule, or always-on when the rule states a global principle with no file scope.
+- An installed skill already covering the topic, found per `### Checking the installed skills` in `${CLAUDE_SKILL_DIR}/references/rule.md`. Point the rule at it rather than restating it.
 
 ## Step 2: resolve the subdir
 
@@ -74,6 +75,13 @@ paths:
 
 Title casing is sentence case, with proper nouns keeping their own casing (`# TypeScript standards`). `${CLAUDE_SKILL_DIR}/references/rule.md` owns the rest of the body shape.
 
+## Step 5: check each bullet
+
+Read `${CLAUDE_SKILL_DIR}/references/checklist.md` and run every bullet of the written rule through it, along with the shape limits and the content test in `rule.md`.
+
+- Rewrite a bullet marked revise and cut one marked drop, then run the checklist again over what changed
+- Report the verdict counts with the path, and name any bullet kept against a criterion with the reason
+
 ## After writing
 
-Emit the full path on its own line: `.claude/rules/project/<subdir>/<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads or writes a matching file, and always-on rules every session.
+Emit the full path on its own line: `.claude/rules/project/<subdir>/<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads or writes a matching file, and always-on rules every session. When a bullet claims outside practice, tell them to cite its source in the commit that adds the rule.

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