An AI coding agent is only as good as the context it starts with — drop it into a repo with no orientation and it guesses at your architecture, conventions, and commands. A good CLAUDE.md (or equivalent project-context file) is the onboarding doc that turns flailing into fluency. This builds yours: the architecture and conventions the agent needs, the commands to run, the guardrails on what not to touch, and a habit to keep it current.
What This Skill Produces
- A structured CLAUDE.md — the sections an agent actually needs: what the project is, architecture/layout, key conventions, the commands (build/test/lint/run), and the do-nots
- The right altitude — enough to orient the agent fast, not an exhaustive doc it drowns in; signal over completeness
- Guardrails — what the agent must not touch, how to run tests before claiming done, and where irreversible actions need a human
- Convention capture — the implicit rules a human learns over months (naming, patterns, where things go) made explicit
- A commands block — the exact commands to build, test, lint, and run, so the agent verifies its own work
- A maintenance habit — updating it as the project changes so it doesn't drift into wrong
Required Inputs
Ask for these if not provided:
- The project — what it is, the stack, rough architecture
- The conventions — the patterns and rules you'd tell a new hire
- The commands — how to build, test, lint, run
- The danger zones — what an agent should never touch or must be careful with
- Your agent — Claude Code, Cursor, etc. (file name/location may differ)
Framework: Orient, Constrain, Verify, Maintain
- Orient fast. Lead with what the project is and its architecture at a glance — the agent needs the map before the details.
- Capture the implicit conventions. The rules a human absorbs over months (where files go, naming, preferred patterns) are exactly what an agent can't infer — write them down.
- Give the commands. Build/test/lint/run commands let the agent verify its own work instead of guessing — this single section prevents most bad output.
- Set guardrails. What not to touch, always-run-tests-before-done, and where a human must approve — so autonomy doesn't become damage.
- Keep the altitude right. Enough to be useful, short enough to be read — prune anything that doesn't change the agent's behavior.
- Maintain it. Update as the project evolves; a stale context file is worse than none because it misleads.
Output Format
CLAUDE.md for [project]
What this is: [one-paragraph orientation + architecture at a glance].
Layout: [key directories/modules and what they do].
Conventions: [naming · patterns · where things go · style].
Commands: build: · test: · lint: · run:.
Guardrails: [do-not-touch · run tests before done · human-approval zones].
Maintenance: [update when X changes — keep it current].
Quality Checks
- Orients the agent to purpose and architecture first
- Makes implicit conventions explicit
- Includes the exact build/test/lint/run commands
- Sets guardrails on danger zones and verification
- Keeps the doc at a readable altitude; sets a maintenance habit
Anti-Patterns
- A novel the agent won't read, or a stub that orients nothing.
- Omitting the commands, so the agent can't verify its work.
- Missing guardrails on irreversible or dangerous actions.
- Assuming the agent infers conventions it has no way to know.
- Writing it once and letting it drift out of date.
Example Trigger Phrases
- "How do I set up a CLAUDE.md for my repo?"
- "Configure my project so Claude Code works well in it."
- "My AI agent keeps misunderstanding my codebase — how do I fix that?"
- "What should go in my project's AI context file?"
- "Onboard an AI coding agent to my project properly."