Anatomy of a .claude/ folder

The map: seven things, one folder

The .claude/ folder is your project’s control panel. Here is everything it can hold, in the order this guide tours them.

1. settings.json — the shared config: permissions, hooks, plugins, environment variables. Committed to git so the whole team gets the same behavior.
2. settings.local.json — your private overrides for this one project. Claude Code keeps it out of git on its own.
3. skills/ — reusable capabilities, each a folder holding a SKILL.md file. Claude discovers them by itself.
4. agents/ — your custom subagents: markdown files with frontmatter describing what they do and which tools they may use.
5. commands/ — your own slash commands, one markdown file each.
6. CLAUDE.md and rules/ — project memory: standing instructions, with path-scoped rules that load only when Claude touches matching files.
7. hooks — your own commands wired into Claude’s lifecycle, configured in settings.json.

A useful mental model: settings.json and hooks are the rules of the room; skills, agents, and commands are the tools on the shelf; CLAUDE.md and rules are the notes on the wall.

1 · The shared config: settings.json

This is the team’s file. Permissions, hooks, plugins, and the environment variables the project needs — everything Claude Code should do the same way for everyone who clones the repository.

Commit it. That is the whole point: anyone who checks out the project gets the same permissions, the same hooks, and the same plugins without configuring anything. Two caveats worth knowing: a few sensitive keys never take effect from a repository file (so a repo you clone can’t quietly grant itself dangerous powers), and some of what you commit only activates after each teammate trusts the folder. To confirm what loaded, run /status inside Claude Code and read the Setting sources line.

{
  "permissions": {
    "allow": ["Bash(npm test:*)", "Bash(npm run lint:*)"],
    "deny": ["Read(./.env)"]
  },
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [
        { "type": "command", "command": ".claude/hooks/block-secret-commit.sh" }
      ]}
    ]
  },
  "env": { "NODE_ENV": "test" }
}

One committed file is the difference between “works on my machine” and “works in every Claude session.”

2 · Your private overrides: settings.local.json

Same folder, opposite purpose: this file is yours alone, for this one project only. Personal permission approvals, experiments you are not ready to share, sandbox URLs — anything the team file shouldn’t carry.

Claude Code applies it over the committed settings.json, so your overrides win without touching the team’s file. And it writes to this file itself: when Claude asks permission to run a Bash command and you pick “Yes, and don’t ask again,” the approval lands here as an allow rule. The first time Claude Code creates the file in a git repository, it adds it to your global git excludes, so it stays out of your commits — if you create it by hand, add it to .gitignore yourself.

3 · Reusable superpowers: skills/

A skill is a folder with a SKILL.md file: instructions Claude loads when they become relevant. Put a skill at .claude/skills/<name>/SKILL.md and every session in the repository can use it — commit it and the team gets it too.

Skills are the cheapest leverage in the folder. Unlike CLAUDE.md content, a skill’s body loads only when Claude actually uses it, so a long playbook costs almost nothing in context until the moment it runs. Create one when you catch yourself pasting the same checklist, procedure, or domain knowledge into chat — or when a section of CLAUDE.md has grown from a fact into a procedure. Claude discovers project skills on its own and can invoke them unprompted when relevant; you can also call one directly with /<skill-name>.

---
name: deploy
description: Ship the web app: build, smoke-test, deploy to staging
---

# Deploy

1. Run `npm run build` and fail fast on errors.
2. Hit `/healthz` on the staging URL; expect HTTP 200.
3. ...

If you paste it twice, skill it. The folder is the team’s shared muscle memory.

4 · Your own crew: agents/

Custom subagents are markdown files with YAML frontmatter, stored in .claude/agents/. Each one is a specialist: its own system prompt, its own tool access, its own model — running in its own context window so the main conversation stays clean.

The frontmatter is the whole API: a name, a short description Claude uses to decide when to delegate, the tools it may touch, and optionally a cheaper model for the job. Keep descriptions short — they all load into context at startup. The markdown body becomes the subagent’s system prompt. Project subagents are discovered by walking up from the working directory, so nested folders can specialize further, and checking them into version control lets the team improve them together.

---
name: code-reviewer
description: Reviews diffs for bugs and style. Use after writing code.
tools: Read, Grep, Glob
model: haiku
---

# Code reviewer

You review uncommitted changes. Be specific: file, line, why it matters.
Read-only: never write or edit.

Subagents are how you parallelize yourself: the right worker, the right tools, none of the context cost.

5 · Canned workflows: commands/

Markdown files in .claude/commands/ become slash commands: type / plus the filename and Claude runs your saved workflow instead of re-deriving it from scratch.

This is the older, simpler format — it still works, and it supports the same frontmatter as skills. The rule of thumb from Anthropic’s docs: prefer a skill for new work, since skills can also carry supporting files alongside the instructions. But when all you need is a prompt you keep retyping — a commit-message format, a test loop, a release checklist — a one-file command is the lightest possible tool.

# Fix the failing tests

1. Run `npm test` and list every failure.
2. Fix them one at a time, smallest change first.
3. Re-run until green. Do not refactor unrelated code.

6 · Project memory: CLAUDE.md and rules/

Standing instructions live here. A CLAUDE.md file can sit at the project root or at .claude/CLAUDE.md; Claude reads it at the start of every session. It is context, not enforced configuration — write concrete, verifiable facts: build commands, conventions, where things live.

For larger projects, .claude/rules/ keeps instructions modular. Each markdown file covers one topic — and with a paths frontmatter field, a rule loads only when Claude works with matching files. Rules without paths load at launch like CLAUDE.md itself. The payoff: instructions that matter for one corner of the codebase stop taxing every session’s context.

---
paths:
  - "src/**/*.test.ts"
---

# Testing rules

- Use vitest. Never use jest.
- Every new API handler needs a test for the unhappy path.

7 · The stage manager’s headset: hooks

Hooks run your own commands at moments in Claude Code’s lifecycle — before a tool call, after one, when the session ends. They are configured in settings.json, which is why they belong in this tour: the folder wires them up, the scripts live wherever you point them (teams commonly keep them under .claude/hooks/).

Each hook names an event, a matcher for when it fires, and a handler — a shell command, a prompt, or an agent. Hooks defined in different settings files merge rather than replace each other, so the team’s hooks and your personal ones coexist. The classic use: a PreToolUse hook that inspects a command before it runs and stops it if it looks dangerous — like a commit carrying secret files.

Hooks are the only item in the folder that can say no: everything else guides, hooks enforce.

FAQ

Takeaways

1. One folder, two scopes. .claude/ configures the project; ~/.claude/ configures you everywhere. Same shape, different reach.
2. Commit the shared, never the local. settings.json goes to git; settings.local.json stays yours, and Claude Code keeps it out of version control for you.
3. Skills are the cheapest leverage. Their instructions load only when used — if you paste it twice, make it a skill.
4. Subagents need three things. A name, the tools they may use, and a description short enough to load at startup. Frontmatter is the whole API.
5. Layer your memory. CLAUDE.md for always-on facts, rules/ for file-scoped ones. Graduate procedures to skills.
6. Hooks are the guardrails. Everything else in the folder guides; hooks configured in settings.json are the only part that can say no.

Sources

Every technical claim in this guide — the folder contents, settings files and their precedence, CLAUDE.md locations, the rules directory, skill and subagent file formats, command files, and hooks configuration — comes from Anthropic’s official Claude Code documentation, read on October 5, 2026. The stage-play analogy, use cases, and file templates are our own.

• Source: Anthropic docs — Settings files and precedence: the project .claude folder, the four settings files, precedence stack, gitignore behavior, trust, /status ↗
• Source: Anthropic docs — How Claude remembers your project: CLAUDE.md locations (.claude/CLAUDE.md), .claude/rules/ with path-scoped rules, the 200-line guidance ↗
• Source: Anthropic docs — Extend Claude with skills: .claude/skills/<name>/SKILL.md, discovery, loads-only-when-used, .claude/commands/ files ↗
• Source: Anthropic docs — Create custom subagents: .claude/agents/ markdown files, frontmatter fields, nested discovery, description budget ↗
• Source: Anthropic docs — settings reference, hooks: events, matchers, handlers, merging across files ↗

Companion reel: this guide will be linked from @theclaudecraft’s “Anatomy of a .claude/ folder” reel once it posts.