Anatomy of the .claude Folder: What It Does and Why It Confuses People

If you've searched for "anatomy of the .claude folder," chances are you're trying to figure out what this folder actually does, why it trips people up, and which parts deserve your attention. That's a fair set of questions. The folder looks simple until you realize it's doing more than storing config files.

A Reddit thread from March 2026 laid this out clearly. A developer who had gotten burned by unclear placement conventions built a cheat sheet covering the .claude/ directory layout, hook events, settings.json, MCP configuration, skill structure, and context-management thresholds. The thread resonated because the folder doesn't just hold settings — it actively shapes what happens when you run commands, invoke skills, and manage agents.

The Core Confusion: Global vs. Project-Level

The single biggest source of confusion is the difference between the global ~/.claude directory and the project-level .claude/ directory.

The global directory sits in your home folder and defines shared behavior across all projects. It includes your personal settings, global MCP server configurations, and skills you want available everywhere. Think of it as your personal defaults.

The project-level .claude/ directory lives inside a specific repository. It overrides or extends the global configuration for that particular project. Project-specific skills, agent definitions, hooks, and MCP configs go here.

When you mix these two layers — putting project-specific behavior in the global directory, or expecting global settings to apply when a project overrides them — the folder starts feeling mysterious. It's not mysterious. It's just scoped, and scope determines precedence.

A practical rule: if a behavior should apply everywhere, put it in ~/.claude. If it belongs to one project, put it in the project's .claude/. When in doubt, start project-level and promote to global only after confirming it works across multiple codebases.

Placement Conventions: Where Things Actually Go

The folder structure isn't arbitrary. Specific types of content belong in specific locations, and getting this wrong is one of the most common mistakes.

Skills belong in .claude/skills/. Each skill gets its own directory containing a SKILL.md file. That SKILL.md is the entry point — it defines what the skill does, how to invoke it, and what it needs. Alongside SKILL.md, you might have scripts/, references/, and assets/ subdirectories depending on the skill's complexity.

Agents go in .claude/agents/, not scattered loose files in the top-level folder. Agents are defined with specific configuration files that the system needs to locate consistently. Loose placement means the system can't interpret what you meant.

Settings live in .claude/settings.json at the project level or ~/.claude/settings.json globally. This is where you configure hooks, permissions, and behavioral defaults.

MCP configurations have their own placement within the settings structure. They define how Claude connects to external tool servers, and mixing MCP config with general settings in the wrong scope can cause silent failures.

The pattern is consistent: structure determines whether the system can interpret your intent. A misplaced skill file isn't just disorganized — it's invisible to the runtime.

Hooks Are Operational, Not Passive

Many developers treat hooks as optional decoration. They're not. Hooks are operational components that execute at specific points in the tool lifecycle.

The most common mistake is overly narrow matching. If you configure a PostToolUse hook that only matches "Write," you'll miss edits made through "Edit" or "MultiEdit" operations. The broader matcher pattern "Edit|MultiEdit|Write" catches more and prevents silent gaps in your automation.

Hook events fire at defined moments: PreToolUse before a tool runs, PostToolUse after it completes, and Notification when the system needs to alert you. Each event type serves a different purpose, and understanding the timing matters for building reliable automation.

A hook that runs PostToolUse to validate generated code is useful. A hook that runs PreToolUse to set up environment variables is useful. A hook configured for the wrong event type is invisible — it doesn't fail loudly, it just never fires.

The configuration directory is not passive storage. It's part of the runtime. Treat it that way.

The Four Things That Actually Matter

When people look at the .claude folder for the first time, everything seems equally important. It's not. Four areas deserve focused attention.

1. Scope. Global vs. project-level is the first decision. Get this wrong and nothing else works as expected. The precedence rules are straightforward — project-level overrides global — but you need to know which layer you're configuring before you start.

2. Placement conventions. Skills need their own directories with SKILL.md. Agents go in agents/. Settings have a defined structure. These aren't suggestions. The runtime looks for content in specific locations, and wrong placement means silent invisibility.

3. Content vs. orchestration. Skills, agents, settings, hooks, and MCP configurations are not equivalent concepts. Skills define reusable capabilities. Agents define autonomous workflows. Settings define behavioral defaults. Hooks define lifecycle automation. MCP configs define external tool connections. Conflating these leads to muddled configurations where you're not sure what controls what.

4. Signs of drift. The documentation for the .claude folder moves fast. What worked in January 2026 may have changed by March. Skill structure conventions, hook event names, and MCP configuration formats all evolve. If your setup stopped working and you didn't change anything, check whether the underlying conventions shifted.

How to Approach the Folder

The .claude folder combines scope, structure, and behavior into a single directory tree. The right way to learn it is in that order.

Start with scope. Understand what lives in the global directory versus the project directory, and why the distinction matters. Then learn placement conventions. Know where skills, agents, settings, and hooks belong, and why the runtime expects them there. Finally, understand behavior. Hooks, MCP configs, and settings aren't just metadata — they change what happens when you run commands.

Once you internalize that three-layer model, the folder stops looking like hidden clutter and starts looking like an operating map. The structure tells you what the system can do, where it looks for instructions, and when it acts on them.

That's the real anatomy of the .claude folder. Not a pile of config files, but a structured interface between your intent and the system's behavior.