# claude-md-and-folder-standards

> A Claude Code skill that encodes the standards for editing any CLAUDE.md — a repo's root CLAUDE.md included — and any file under .claude/: size limits, where content belongs, skill conventions, settings hygiene, and token awareness, so your agent config stays lean and cheap.

- **Difficulty:** Intermediate
- **Tags:** Claude Code, CLAUDE.md, Skills, Configuration
- **Added:** Jul 3, 2026
- **Source:** https://prostdev.com/skill/claude-md-and-folder-standards

---
## What it does

`claude-md-and-folder-standards` is a Claude Code [skill](https://docs.claude.com/en/docs/claude-code/skills)
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.

````markdown title="SKILL.md"
---
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.
````