.claude directory

What is the .claude directory?

Claude Code reads instructions, settings, skills, subagents and memory from your project’s .claude directory and then the ~/.claude directory in your home directory. Commit things in this directory to share them with your team.

Common files in the .claude directory

CLAUDE.md

Project-specific instructions that provide persistent information across all Claude sessions.

Put your project’s conventions, common commands and architectural context here so that Claude operates with the same assumptions as your team.

.mcp.json

Configures Model Context Protocol (MCP) servers that give Claude access to external tools like databases, APIs or browsers. This file is for project-scoped MCP servers that your whole team uses. For personal servers, use ~/.claude.json instead.

Example file:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "${NOTION_TOKEN}"
      }
    }
  }
}

.worktreeinclude

Lists the gitignored files to copy from your main repository into each new worktree. By default, new worktrees ignore untracked files so use this file to tell Claude which gitignored files should be coped to new worktrees. Example files you might add include .env or .env.local.

Example file:

# Local environment
.env
.env.local

# API credentials
config/secrets.json

settings.json

Settings that configure how Claude Code works. Example settings include:

• permissions: allow, denoy or prompt before Claude uses specific tools or commands.
• hooks: run your own scripts on events like before a tool call or a file edit.
• statusLine: customise the line shown at the bottom while Claude works.
• model: pick a default model for the project.
• env: environment variables to set in every session.
• outputStyle: select a custom output style from.

Example file:

{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  },
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
      }]
    }]
  }
}

settings.local.json

Personal settings that take precedence over the project defaults at settings.json. Array settings like permissions.allow merge with those from settings.json; scalar settings like model take precedence over settings.json.

Example:

{
  "permissions": {
    "allow": [
      "Bash(docker *)"
    ]
  }
}

Here, we’ve told Claude that it should run docker commands without prompting us.

rules/*.md

Add rules here that should only be loaded into the context window when Claude is working with specific types / patterns. As an example, you might add a rules/testing.md file with the following content:

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

# Testing Rules

- Use descriptive test names: "should [expected] when [condition]"
- Mock external dependencies, not internal modules
- Clean up side effects in afterEach

Now, this rule will only load into the context when Claude is working on test files (**/*.test.ts or **/*.test.tsx files.

Another example:

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

# API Design Rules

- All endpoints must validate input with Zod schemas
- Return shape: { data: T } | { error: string }
- Rate limit all public endpoints

skills/

Add your project’s skills here. Consider an example skills/security-review/ folder:

skills/
  security-review/
    SKILL.md
    checklist.md

Suppose its SKILL.md file looked like this:

---
description: Reviews code changes for security vulnerabilities, authentication gaps, and injection risks
disable-model-invocation: true
argument-hint: <branch-or-path>
---

## Diff to review

!`git diff $ARGUMENTS`

Audit the changes above for:

1. Injection vulnerabilities (SQL, XSS, command)
2. Authentication and authorization gaps
3. Hardcoded secrets or credentials

Use checklist.md in this skill directory for the full review checklist.

Report findings with severity ratings and remediation steps.

This skill uses disable-model-invocation: true which means only you can trigger it; Claude never invokes it on its own.

The !<code> line runs a shell command and injects its output into the prompt.

$ARGUMENTS substitues whatever you typed after the skill name. For example, if you typed /security-review feature/add-login, Claude will essentially run git diff feature/add-login.

agents/

Each markdown file in agents/ defines a subagent with its own system prompt, tool access, and optionally its own model. Subagents run in a fresh context window, keeping the main conversation clean. Subagents are useful for parallel work or isolated tasks.

Example: agents/code-review.md

---
name: code-reviewer
description: Reviews code for correctness, security, and maintainability
tools: Read, Grep, Glob
---

You are a senior code reviewer. Review for:

1. Correctness: logic errors, edge cases, null handling
2. Security: injection, auth bypass, data exposure
3. Maintainability: naming, complexity, duplication

Every finding must include a concrete fix.