CLAUDE CODE · LESSON 18

Explore the .claude Directory

The hidden /.claude folder is where all of Claude Code's project intelligence lives — instructions, hooks, agents, skills, and settings. Learn what each file does so you can configure Claude like a pro.

CLAUDE.mdsettings.jsonhooks/agents/skills/

The Full Directory Tree

When you work with Claude Code in a project, a .claude/ folder is created at the project root. Here is everything it can contain:

your-project/

📁 .claude/all config

📄 CLAUDE.mdinstructionsProject-level instructions for Claude

📄 settings.jsonshared configHooks, permissions — committed to Git

📄 settings.local.jsonprivateYour local overrides — gitignored

📁 hooks/automation

📄 format.shCustom hook scripts go here

📄 guard.sh

📁 agents/sub-agents

📄 reviewer.mdCustom sub-agent definitions

📄 researcher.md

📁 skills/slash commands

📄 add-types.mdCustom /slash-command definitions

📄 write-changelog.md

📁 commands/legacy

📄 my-command.mdOlder slash-command format

ℹ️You rarely create these files by hand. Claude Code creates CLAUDE.md and settings.json automatically; you edit them to customise behaviour. Run claude --init to scaffold a project-ready .claude/ folder.

File by File

📄

.claude/CLAUDE.md

Project instructions · committed to Git

This is the most important file. Every time a session starts, Claude reads it automatically. Use it to describe the project, its conventions, forbidden patterns, and preferred tools — so Claude always has the right context.

# Project: Inventory API

## Stack
- Node.js 20, Express 5, PostgreSQL 16
- Tests: Vitest — run with `npm test`
- Lint: ESLint + Prettier — run with `npm run lint`

## Conventions
- All DB queries must use parameterised statements
- Never commit .env files
- Feature branches follow: feat/<ticket-id>-short-description

📄

.claude/settings.json

Shared project config · committed to Git

Holds hooks, permission rules, and other project-wide settings. Because it is committed, every team member gets the same Claude behaviour automatically.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/lint.sh"
          }
        ]
      }
    ]
  }
}

📄

.claude/settings.local.json

Private overrides · gitignored

Same format as settings.json but gitignored. Use it for personal preferences — your own extra hooks, local path overrides, or developer-only permission rules — that you don't want to push to the repo.

📁

.claude/hooks/

Shell scripts called by hook events

Store your hook shell scripts here. Reference them from settings.json using the $CLAUDE_PROJECT_DIR variable so paths stay correct regardless of where Claude is run from.

#!/bin/bash
# .claude/hooks/lint.sh
FILE=$(cat | jq -r '.tool_input.file_path // empty')

if [[ "$FILE" == *.ts || "$FILE" == *.tsx ]]; then
  npx eslint --fix "$FILE" 2>/dev/null
fi

exit 0

📁

.claude/agents/

Custom sub-agent definitions

Each Markdown file here defines a custom sub-agent with a YAML frontmatter header. Claude Code spawns the agent when instructed, giving it a focused role and optional tool restrictions.

---
name: code-reviewer
description: Reviews code for security issues and code quality
tools:
  - Read
  - Grep
  - Glob
---

You are a focused code reviewer. Scan for:
- Security vulnerabilities (SQL injection, XSS, hardcoded secrets)
- Missing error handling
- Performance anti-patterns

Report findings clearly with file and line references.

📁

.claude/skills/

Custom slash-command definitions

Each file becomes a /skill-name slash command inside Claude Code. Use$ARGUMENTS as a placeholder for anything typed after the command name.

---
name: add-types
description: Add TypeScript types to a JavaScript file
---

Convert the file at $ARGUMENTS to TypeScript:
1. Add explicit types to all function parameters and return values
2. Replace `any` with proper types where possible
3. Keep the same logic — only add type annotations, no refactoring

Invoke with: /add-types src/utils/helpers.js

At a Glance

File / Folder	Purpose	Committed?	Scope
`.claude/CLAUDE.md`	Project instructions for Claude	Yes	Project
`.claude/settings.json`	Hooks, permissions (shared)	Yes	Project
`.claude/settings.local.json`	Personal overrides	No	Developer
`.claude/hooks/`	Hook shell scripts	Yes	Project
`.claude/agents/`	Custom sub-agent definitions	Yes	Project
`.claude/skills/`	Custom slash commands	Yes	Project

Git Hygiene

Add this block to your project's .gitignore to keep private files out of version control while committing the shared config:

.gitignore

# Claude Code — keep private settings out of Git
.claude/settings.local.json

# Commit everything else in .claude/ to share with the team
# .claude/CLAUDE.md
# .claude/settings.json
# .claude/hooks/
# .claude/agents/
# .claude/skills/

💡Type /memory inside Claude Code to open a guided editor for CLAUDE.md — you can add, edit, or remove instructions without leaving the chat.

📂Hook scripts in .claude/hooks/ must be executable. Run chmod +x .claude/hooks/*.sh after creating them, or Claude Code won't be able to call them.

🤝Committing .claude/ (minus settings.local.json) is a great team practice — every developer gets the same hooks, agents, and slash commands the moment they clone the repo.

What's Next

You know your way around the .claude/ directory. Next: integrate Claude Code directly into your VS Code editor for an in-editor experience.

← PREVIOUS

How Claude Code Works

Claude Code in VS Code