---

name: claude-project-setup description: "Set up a repo or project so an AI coding agent works well in it — the CLAUDE.md, the context, the guardrails, and the conventions the agent needs to be useful instead of lost. Use when asked how do I set up CLAUDE.md, configure my repo for Claude Code, my AI agent keeps getting my project wrong, or onboard an AI agent to my codebase. Produces a structured CLAUDE.md/project-context file (architecture, conventions, commands, do-nots), the right level of detail (enough to orient, not a novel), the guardrails that keep the agent safe (what not to touch, how to test), and a maintenance habit so it stays current — turning a repo an agent flails in into one it navigates like a teammate."

Claude Project Setup

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

1. Orient fast. Lead with what the project is and its architecture at a glance — the agent needs the map before the details.
2. 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.
3. 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.
4. Set guardrails. What not to touch, always-run-tests-before-done, and where a human must approve — so autonomy doesn't become damage.
5. Keep the altitude right. Enough to be useful, short enough to be read — prune anything that doesn't change the agent's behavior.
6. 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."