Anatomy of the .claude/ folder
If you use Claude Code, there is a folder that controls everything. It is called .claude/ and it lives inside your project. Here is exactly what is inside it, what each piece does, and why each one is different.
■ Purple = shared with team (if you commit to Github) ■ Green = your machine only ■ Blue = behaviour and workflows
Top level - your-project/
shared | How Claude should behave |
local | Your personal behaviour override |
Both tell Claude HOW to behave. The difference: CLAUDE.md is shared with your whole team. CLAUDE.local.md stays on your machine only. |
.claude/ - the control center
Everything inside this folder shapes how Claude operates.
settings.json | shared | What Claude can access |
settings.local.json | local | Your personal access overrides |
CLAUDE files = what to do. Settings files = what Claude is allowed to touch. Completely different layer. |
commands/ | you trigger | Custom /slash shortcuts |
rules/ | always on | Passive rules every response follows |
skills/ | on demand | Instruction files Claude reads when needed |
📁 security-review/
📄 SKILL.md
📁 deploy/
📄 SKILL.md
agents/ | becomes a persona | Claude takes on a specialist role |
rules = always on · commands = you trigger · skills = read on demand · agents = Claude becomes someone |
The key differences explained
CLAUDE.md vs settings.json
CLAUDE.md tells Claude what to do - tone, rules, behaviour. settings.json tells Claude what it is allowed to touch - which tools it can run, which folders it can access. One is instructions. One is permissions.
rules/ vs commands/ vs skills/
rules/ are always running in the background. You never think about them. Like autopilot.
commands/ are shortcuts you trigger manually. Nothing happens until you type /project:deploy.
skills/ are instruction files Claude reads when you ask it to do a specific job. Not automatic - you reference them or configure them to trigger.
skills/ vs agents/
A skill is a task. It tells Claude how to do one specific thing, like reviewing a contract.
An agent is an identity. Claude becomes a specialist character - a code reviewer, a security auditor - and stays in that lane without bleeding into other roles.
Skills are verbs. Agents are nouns.
