add-section
Skill0 starsChanged 5 months agoApache-2.0View on GitHub
Add, remove, or rename a numbered section (§N) or lettered appendix in the methodology, applying the append-only rule and updating every cross-reference and count/range claim. Use whenever a methodology section or appendix is added or removed.
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- close-planSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 41
Add a
CHANGELOG.md[Unreleased]line: if the change is user-facing (most are).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add or remove a methodology section or appendix
Section numbers (§N) and appendix letters (A–O) are stable, load-bearing identifiers
(the CLAUDE.md invariant). The hard part is never the prose — it is updating every
cross-reference and every count/range claim so nothing dangles or goes stale. The
consistency hook catches a dangling §/Appendix reference, but it does not catch a
stale count ("fifteen") or range ("A–O"), so those are on you.
Rules
- Append-only. A new section takes the next free number; a new appendix the next free
letter. Never renumber or re-letter to keep things tidy — the number/letter is an
identifier, not a sort key (ADR 0001). An appendix goes in its thematic file under
docs/appendices/; its letter need not match the file order. - Sections live in
docs/methodology.md(before the appendices pointer at the end); appendices live indocs/appendices/*.md, grouped by type, indexed bydocs/appendices/README.md.
Steps
- Add the content in the right place (append the section to
docs/methodology.md, or the appendix to the matchingdocs/appendices/file), and updatedocs/appendices/README.mdif it is an appendix. - Ripple the count/range claims. These are not hook-checked. The grep is the source of
truth — run it and update every hit; the list below is a starting checklist, not a complete one
(carriers drift, so trust the grep):
Usual carriers:grep -rnE 'A–[A-Z]|[0-9]+ drop-in|[Ff]ourteen|[Ff]ifteen|[Ss]ixteen' --include='*.md' . \ | grep -v docs/local | grep -v docs/plans/archiveREADME.md(the count, the invariant mention, the What's-here entry),CLAUDE.md(Layout + the invariant),CHANGELOG.md, the appendices pointer at the end ofdocs/methodology.md,.claude/agents/code-reviewer.md,.claude/rules/definition-of-done.md,.claude/commands/plan.md, and the reviewer's.claude/agent-memory/code-reviewer/project-repo-shape.md. - Add a
CHANGELOG.md[Unreleased]line if the change is user-facing (most are). - Run the consistency hook on every edited in-scope Markdown file (
docs/exceptdocs/local/anddocs/plans/, plusREADME.md,CHANGELOG.md,templates/; it no-ops on.claude/) — confirms no dangling reference:printf '{"tool_input":{"file_path":"%s"}}' "$PWD/<file>" \ | CLAUDE_PROJECT_DIR="$PWD" bash .claude/hooks/docs-consistency.sh; echo "exit=$?" - Run the
code-reviewersubagent on the diff and clear any Critical or Warning before merge.
Out of scope
- Renumbering or re-lettering existing sections/appendices. If that ever seems necessary, raise it as a decision (ADR) — do not do it as a side effect of adding something.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

