# claude-folder-standards

> A Claude Code skill that encodes the rules for editing anything in your .claude folder — CLAUDE.md 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
- **Published:** Jul 3, 2026
- **Source:** https://prostdev.com/skill/claude-folder-standards

---
## What it does

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