CLAUDE.md & Folder Standards

What it does

claude-md-and-folder-standards is a Claude Code skill that the agent invokes before it touches your agent configuration — any CLAUDE.md (a repo’s root CLAUDE.md included, even though it lives outside .claude/) or any file under .claude/ (skills, settings.json, hooks). It encodes a set of rules for keeping that config lean: a hard line limit on CLAUDE.md, a decision table for where a given instruction belongs, conventions for authoring skills (including when a cheaper model can run one), and settings hygiene.

The point is fighting config bloat before it starts. Left unchecked, CLAUDE.md grows into a dumping ground of “just in case” advice — and because it’s loaded into context every single turn, every stale line is a tax you pay on every message. This skill makes the agent stop and ask “should this even live here?” before it writes.

When to use it

Invoke it whenever you’re about to modify agent configuration:

• Adding a rule or convention to a CLAUDE.md (root or nested).
• Deciding whether something should be a skill, a hook, an import, or an inline rule.
• Authoring a skill — including whether it’s mechanical enough to hand to a cheaper model.
• Editing shared vs. personal settings, or tightening a permission pattern.

It’s most valuable on a mature project where the .claude folder has accumulated several skills, agents, and docs — exactly the point where “where does this go?” stops being obvious.

How it works

The skill is just a Markdown file — a short frontmatter block (its name and a description that tells the agent when to invoke it) followed by plain-English rules. There’s no code to run; Claude reads the standards and applies them as it edits.

A few ideas in here that generalize to any config-hygiene skill:

• Put a hard number on the soft rule. “Keep it short” gets ignored; “max 200 lines, move the overflow to a skill” is checkable. The skill closes with a literal pre-save checklist.
• Make “where does this go?” a decision table. Every-session-and-prevents-mistakes goes inline; specialized-to-one-workflow becomes a skill; must-run-deterministically becomes a hook; a machine-specific override goes in a .local file.
• Know what actually defers. A plain [link](path) to a doc is read only when a task needs it — cheap. An @path import is always-on: it’s expanded into context at launch every session, so it costs the same as inlining. The skill spells this out so “referencing” a big doc doesn’t quietly cost as much as pasting it.
• Route skills to the cheapest model that can run them. A mechanical, self-contained skill can set model: haiku/sonnet in its frontmatter; judgment-heavy or high-stakes ones inherit the session model, because a mid-turn switch busts the prompt cache both ways.
• Frame the cost. The token-awareness section reframes each line of CLAUDE.md as a recurring per-turn charge — which is the argument that actually keeps it lean.

The skill definition

Here’s the actual SKILL.md, verbatim — copy it, adapt the numbers to your own project, and drop it in your project’s skills directory.

---
name: claude-md-and-folder-standards
description: Standards for editing any CLAUDE.md (each repo's root CLAUDE.md included — it lives outside .claude/ but these rules still govern it) and any file under .claude/ (skills, settings.json, hooks). Invoke before modifying any of them.
---

# Standards for CLAUDE.md & `.claude/` files

Follow these rules when creating or modifying **any `CLAUDE.md`** — each repo's **root** `CLAUDE.md`
included; it lives *outside* `.claude/`, but these rules still apply to it — **or any file under
`.claude/`** (skills, `settings.json`, hooks).

## CLAUDE.md Rules

- **Max 200 lines.** If it exceeds this, move content to skills.
- Only include instructions Claude would get WRONG without. Delete anything obvious.
- Never duplicate what can be inferred from project files (tsconfig, package.json, etc.).
- No frequently changing info (versions, team members, URLs that rotate).
- No self-evident advice ("write clean code", "follow best practices").
- Structure: Overview > Setup > Code style > Testing > Git workflow > Gotchas.
- **Don't inline detailed or occasional content — reference it.** For subsystem detail you read only
  *sometimes*, use a plain `[link](path)` to a repo-local doc — it's read on demand, so it costs
  nothing until a task needs it (cheapest). Reserve `@path` imports for the rare doc you genuinely
  need *every* session.
- **`@path` imports are ALWAYS-ON** — expanded into context at launch (up to 4-hop nesting), so they
  cost the same as inlining, every session. They organize; they DON'T defer. NEVER `@`-import a big
  doc — link it with a plain path instead.

## Deciding Where Content Belongs

| If the instruction... | Put it in... |
|---|---|
| Applies every session, prevents mistakes | CLAUDE.md |
| Is specialized to one workflow/domain | A skill |
| Is a personal/machine-specific override | CLAUDE.local.md or settings.local.json |
| Must execute deterministically (not advisory) | A hook |
| Defines a reusable subagent with scoped tools | agents/ |

## Skills Rules

- Prefer skills over long CLAUDE.md sections for specialized knowledge.
- Keep each skill focused on one workflow or domain.
- Name the folder descriptively with kebab-case.
- Include `name` and `description` in the frontmatter.
- Target 50-80 lines per skill. Under 120 max.
- Ask per skill: could a cheaper model run it? Only if the workflow is mechanical (judgment spelled
  out in the body) AND self-contained — then set frontmatter `model: haiku`/`sonnet` (optionally
  `effort:`), ideally with `context: fork`. Otherwise inherit: the override lasts the rest of the
  turn (downgrading whatever task invoked the skill) and a mid-turn model switch busts the prompt
  cache both ways. Judgment-heavy or high-stakes skills (prod migrations, shared-config edits,
  session summaries) always inherit.

## settings.json Rules

- Project-level `settings.json` is shared (checked in). No secrets, no personal paths.
- Personal overrides go in `settings.local.json` (must be in .gitignore).
- Permissions: prefer specific patterns (`Bash(npm test *)`) over broad wildcards.
- Set model and effort at session start to preserve prompt cache.

## Token Awareness

When adding ANY content to .claude files, consider token cost:

- Every line of CLAUDE.md costs ~2-4 tokens PER TURN, every turn, every session.
- Ask: "Is this worth paying for on every single message?"
- If the answer is "only sometimes" — it's a skill, not CLAUDE.md.
- Prefer terse, imperative rules over explanatory prose.
- Use bullet points, not paragraphs.

## Anti-Patterns to Reject

- Adding "use TypeScript" when tsconfig.json exists
- Listing every file in the project
- Pasting entire style guides (link them instead)
- Adding instructions "just in case" — if it's not causing errors, don't add it
- Duplicating content already in another file (README, CONTRIBUTING, etc.)

## Before Saving Changes

1. Count lines. Is CLAUDE.md still under 200?
2. Could this be a skill instead? If yes, make it one.
3. Is this already inferrable from project files? If yes, skip it.
4. Read it as if paying per-word. Cut filler.