The .claude Folder Map — what actually lives inside Claude Code (+ drop-in starter)

claude-folder-map.md

The .claude Folder Map — what actually lives inside Claude Code

Everyone edits CLAUDE.md. But that's one file in a folder most people never open. Here's the whole .claude/ folder — what each piece does, and a starter you can drop into any project.

The map

your-project/
├── CLAUDE.md              ← project memory: who you are, your stack, your rules (auto-loaded every session)
├── .mcp.json             ← MCP servers for this project (GitHub, Playwright, Supabase…)
└── .claude/
    ├── settings.json      ← permissions, env vars, model, and hook wiring (shared, committed)
    ├── settings.local.json← your personal overrides (gitignored)
    ├── skills/            ← reusable skills Claude loads on trigger
    │   └── <name>/SKILL.md
    ├── commands/          ← your own slash-commands  →  /deploy, /review …
    │   └── deploy.md
    ├── agents/            ← subagent definitions Claude can spawn in parallel
    │   └── reviewer.md
    └── hooks/             ← scripts that run automatically on events (referenced from settings.json)
        └── format-on-edit.sh

What each one does

Piece	What it is	Why it matters
CLAUDE.md	Plain-markdown context, auto-read at session start	Stop re-explaining your stack, style and rules every chat
settings.json	Permissions (allow/deny), env vars, model, hook config	Lets Claude act without asking every time; wires your hooks
skills/	SKILL.md files with a name + trigger description	Package a workflow once, Claude loads it on cue
commands/	Markdown files → /name slash-commands	Your own repeatable prompts as one command
agents/	Subagent specs (frontmatter: name, tools, model)	Fan out work to parallel specialists
hooks/	Shell scripts fired on events (PreToolUse, PostToolUse, Stop…)	Auto-format, guard actions, notify — deterministically
.mcp.json	MCP server list for the project	Give Claude hands: browser, GitHub, DB, docs

Drop-in starter

Create the folder in any project:

mkdir -p .claude/{skills,commands,agents,hooks}

.claude/settings.json — a sane starting point:

{
  "permissions": {
    "allow": ["Bash(git status)", "Bash(git diff:*)", "Read", "Edit"],
    "deny": ["Bash(rm -rf:*)"]
  },
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": ".claude/hooks/format-on-edit.sh" }] }
    ]
  }
}

.claude/commands/review.md — your first slash-command (/review):

Review the current git diff for bugs, missing tests, and style issues.
Report only high-confidence findings, most severe first.

.claude/agents/reviewer.md — your first subagent:

---
name: reviewer
description: Reviews changed code for correctness and style.
tools: Read, Grep, Bash
---
You are a senior reviewer. Read the diff, flag real bugs and risky changes only.

Reload with /reload (or restart Claude Code) and you're running a system, not a chatbot.

---

Built by @buildwith.conrad — one Claude workflow worth stealing every week.