claude-folder-standards
Keep CLAUDE.md, skills, and settings lean — because every line costs tokens on every turn.
What it does
claude-folder-standards is a Claude Code skill
that the agent invokes before it touches anything in your .claude directory — CLAUDE.md,
settings.json, a skill, or a hook. 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, 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
CLAUDE.md. - Deciding whether something should be a skill, a hook, or an inline rule.
- 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.
- Frame the cost. The token-awareness section reframes each line of
CLAUDE.mdas 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-folder-standards
description: Rules for editing .claude folder files. Invoke before modifying CLAUDE.md, settings.json, skills, or hooks.
---
# Standards for .claude Folder Files
Follow these rules when creating or modifying any file in the `.claude` directory.
## 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 detailed API docs — link with `@path/to/doc` instead.
- 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.
- Use `@file` imports to reference docs without inlining them.
## 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.
## 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.