Mastering Claude Code: Complete Guide to .claude Folder, Commands, Skills & Agents

Two .claude Directories

Claude Code uses two separate .claude folders: a project‑level folder inside the repository (shared via Git) and a global folder in your home directory (~/.claude) that stores personal preferences and local state such as session history.

CLAUDE.md – The Core Prompt

The CLAUDE.md file is the first thing Claude reads when a session starts; everything written here becomes part of the system prompt. It should contain commands, build/test scripts, architectural decisions, hidden pitfalls, import conventions, and a concise module layout. Keep the file under 200 lines to avoid context overload.

# Project: Acme API
## Commands
npm run dev      # Start dev server
npm run test      # Run tests (Jest)
npm run lint      # ESLint + Prettier check
npm run build     # Production build
## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- Handlers in src/handlers/
- Types in src/types/
## Conventions
- Use zod for request validation
- Return shape always { data, error }
- Never expose stack traces
- Use the logger module, not console.log
## Watch out for
- Tests use a real local DB; run `npm run db:test:reset` first
- Strict TypeScript: no unused imports

CLAUDE.local.md – Personal Overrides

Create a CLAUDE.local.md in the project root for settings that should not be committed. The file is automatically added to .gitignore and can contain personal testing tools, preferred coding styles, or any rule you want Claude to apply only for yourself.

rules/ – Modular, Path‑Scoped Directives

When a single CLAUDE.md becomes unwieldy, split directives into separate markdown files under .claude/rules/. Each file can include a YAML front‑matter with a paths: array to limit the rule to specific glob patterns (e.g., src/api/**/*.ts).

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
# API Design Rules
- All handlers return { data, error } shape
- Use zod for request body validation
- Never expose internal error details to clients

commands/ – Custom Slash Commands

Any markdown file placed in .claude/commands/ becomes a slash command. The filename becomes the command name (e.g., review.md creates /project:review). Commands can embed shell output using !`git diff …` and accept arguments via $ARGUMENTS.

---
description: Review the current branch diff for issues before merging
---
## Changes to Review
!`git diff --name-only main...HEAD`
## Detailed Diff
!`git diff main...HEAD`
Review the above changes for:
1. Code quality issues
2. Security vulnerabilities
3. Missing test coverage
4. Performance concerns
Give specific, actionable feedback per file.

skills/ – Reusable Workflows

Skills are markdown packages that Claude can invoke automatically when the conversation matches their description. Each skill lives in its own subdirectory with a SKILL.md (YAML front‑matter describing when to run) and optional detailed guides.

---
name: security-review
description: Comprehensive security audit. Use when reviewing code for vulnerabilities, before deployments, or when the user mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities:
1. SQL injection and XSS risks
2. Exposed credentials or secrets
3. Insecure configurations
4. Authentication and authorization gaps
Report findings with severity ratings and remediation steps.
Reference @DETAILED_GUIDE.md for our security standards.

agents/ – Specialized Sub‑Agents

For complex tasks you can define dedicated agents in .claude/agents/. Each markdown file specifies a system prompt, allowed tools, and a preferred model (e.g., sonnet for cost‑effective reads, opus for heavy lifting).

---
name: code-reviewer
description: Expert code reviewer. Use proactively when reviewing PRs, checking for bugs, or validating implementations before merging.
model: sonnet
tools: Read, Grep, Glob
---
You are a senior code reviewer focused on correctness and maintainability.
When reviewing code:
- Flag bugs, not just style issues
- Suggest specific fixes, not vague improvements
- Check edge cases and error‑handling gaps
- Note performance concerns only when they matter at scale

settings.json – Permission & Configuration Model

The .claude/settings.json file defines what Claude may do. It contains a JSON schema reference, an allow list for safe commands (e.g., Bash(npm run *), Bash(git status)), and a deny list for destructive actions (e.g., rm -rf *, curl *, reading .env files). Operations not listed trigger a confirmation prompt.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

settings.local.json – Personal Permission Tweaks

Analogous to CLAUDE.local.md, a .claude/settings.local.json file can hold personal overrides and is automatically ignored by Git.

Global ~/.claude Folder

The home‑directory ~/.claude stores personal CLAUDE.md, project memories, shared commands, skills, and agents. It is rarely edited directly, but understanding its role helps when you need to clear stale memory or troubleshoot unexpected behavior.

Full Integration Overview

All components—project‑level .claude folder, global ~/.claude, CLAUDE.md, rules, commands, skills, agents, and settings—work together to form a protocol that tells Claude who you are, what the project does, and which rules to follow. The clearer the definitions, the less time Claude spends on clarification and the more time it spends on productive work.

Practical Onboarding Steps

Run /init in Claude Code to generate a starter CLAUDE.md and trim it to essential points.

Add a .claude/settings.json file with allow/deny rules appropriate for your stack (e.g., permit npm run *, deny reading .env).

Create a few project‑level commands such as a code‑review or issue‑fix command.

When CLAUDE.md grows, split recurring directives into .claude/rules/ files and scope them with paths as needed.

Add a personal ~/.claude/CLAUDE.md for preferences that should apply to every repository.

Key Insight

The .claude folder is essentially a contract between you, your team, and Claude. Precise, modular definitions reduce the back‑and‑forth with the model and let Claude focus on delivering value.