agentleFS
tcrosslandtcrossland/claude-code-methodology/.claude/skills/add-section/SKILL.md

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.

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
  1. Very specific:

    Add a CHANGELOG.md [Unreleased] line: if the change is user-facing (most are).

    line 41

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 in docs/appendices/*.md, grouped by type, indexed by docs/appendices/README.md.

Steps

  1. Add the content in the right place (append the section to docs/methodology.md, or the appendix to the matching docs/appendices/ file), and update docs/appendices/README.md if it is an appendix.
  2. 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):
    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/archive
    Usual carriers: README.md (the count, the invariant mention, the What's-here entry), CLAUDE.md (Layout + the invariant), CHANGELOG.md, the appendices pointer at the end of docs/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.
  3. Add a CHANGELOG.md [Unreleased] line if the change is user-facing (most are).
  4. Run the consistency hook on every edited in-scope Markdown file (docs/ except docs/local/ and docs/plans/, plus README.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=$?"
  5. Run the code-reviewer subagent 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.