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