writing-a-good-claude-md Skill
Based on "Writing a good CLAUDE.md" by Kyle (November 25, 2025), published on the HumanLayer Blog.
Help users write, audit, and improve CLAUDE.md (or AGENTS.md) files for AI coding agent harnesses.
Core Mental Model
CLAUDE.md is an onboarding document, not a configuration dump. It answers three questions:
- WHY — What is the purpose of this project and its components?
- WHAT — What is the tech stack, project structure, and map of the codebase?
- HOW — How does Claude actually work on this project? (build, test, verify commands)
Everything else should live elsewhere.
The Six Principles (Summary)
| # | Principle | Key Rule |
|---|---|---|
| 1 | Less is More | Budget ~100–150 instructions; target < 300 lines, ideally < 100 |
| 2 | Universally Applicable Only | Every instruction must apply to every task in the codebase |
| 3 | Progressive Disclosure | Give Claude a map to find info, not all info upfront |
| 4 | Don't Use Claude as a Linter | Code style belongs in deterministic tools, not CLAUDE.md |
| 5 | Craft Manually | Never trust auto-generated CLAUDE.md; write every line intentionally |
| 6 | Understand Why Claude Ignores | Instructions judged irrelevant get skipped — make every one count |
Audit Checklist
| Check | Question |
|---|---|
| Universality | Is every instruction applicable to *every* task the agent might do? |
| Length | Is it under 300 lines? Could it be under 100? |
| Linter work | Does it include code style rules that a formatter could enforce? |
| Stale snippets | Does it paste code that could go stale? Use file:line refs instead |
| Instruction count | Count bullets/rules. Is it approaching 50+? |
| Auto-generated | Does it look like it was generated by /init? If so, it needs a rewrite |
| Progressive disclosure | Are domain-specific docs referenced rather than inlined? |
| Hotfix accumulation | Are there specific one-off instructions that suggest workarounds rather than structure? |
Template: Minimal CLAUDE.md
# Project Name
Brief description of what this project does and why it exists (2-3 sentences).
## Stack & Structure
- **Frontend**: [framework, location]
- **Backend**: [framework, location]
- **Shared packages**: [names and purpose]
- **Key config**: [important files/locations]
## Working on This Project
Build: `<command>`
Test: `<command>`
Typecheck: `<command>`
Lint: `<command>`
Always verify your changes compile and tests pass before considering a task done.
## Reference Docs
Read these files when relevant to your current task — don't read all of them upfront:
| File | When to read |
| ---------------------------- | --------------------------- |
| `agent_docs/architecture.md` | Understanding system design |
| `agent_docs/database.md` | Working with data models |
| `agent_docs/testing.md` | Writing or running tests |
| `agent_docs/deployment.md` | Deploying or CI/CD work |Read On Demand
| Read When | File |
|---|---|
| Full detail on all 6 principles with examples and reasoning | Six Principles Detailed |
| Anti-patterns table, local CLAUDE.md notes, writing workflow | Anti-Patterns & Local Files |