The .claude folder nobody looks at (and it changes everything)

The .claude folder is the invisible brain of Claude Code. Most people never open it.

What 90% of users don't know

When you launch Claude Code for the first time, it silently creates a .claude folder in your project directory. And another one in your home directory. Most developers never touch these files.

That's a mistake. This folder is Claude Code's most powerful configuration interface. Not just a vaguely documented CLAUDE.md file, not just permissions. The entire customization system.

The .claude folder is the difference between using Claude Code at 10% and making it actually work for you.

The two .claude folders: project vs personal

First thing to understand: there are two distinct .claude folders, with very different roles.

The .claude folder in your project contains the rules, commands, skills, and agents specific to that project. This is what you share with your team via Git. Everyone works with the same rules, the same slash commands, the same skills.

The ~/.claude folder in your home directory is your personal playbook. Your preferences, your shortcuts, and most importantly: your entire session history. Every Claude Code conversation is stored in a JSON file somewhere in this folder. If you're looking for a session from three weeks ago, that's where it is.

To see what each one contains, a quick bash command inside Claude Code:

!ls .claude/
!ls ~/.claude/

CLAUDE.md: think router, not encyclopedia

This is the most common mistake: turning CLAUDE.md into a 300-line wall of text that documents absolutely everything. Architecture, code conventions, email style, financial report formats, all in a single file.

The problem: Claude reads this file in its entirety at every session. The longer it is, the more context you waste for nothing.

The right approach: CLAUDE.md as a router. 50 lines maximum. The file tells Claude where to look for each type of task:

# For email drafting: see .claude/rules/email-drafting.md
# For financial reports: see .claude/rules/financial-reports.md
# For brief writing style: see .claude/rules/brief-writing.md

Claude only loads specific rules when they're relevant. The result: preserved context, more precise instructions, less drift between sessions.

It's the same logic as AutoDream and persistent memory between sessions: only load what's needed at the right moment.

Rules: compartmentalize each workflow

The .claude/rules/ folder is the least known and most useful part of the entire Claude Code ecosystem.

Each Markdown file in this folder is a rule dedicated to a specific type of task. Email, brief, report, code review, commit format, documentation writing... each one a separate file.

Why it's powerful: these rules are iterative. Every time Claude does something that doesn't match what you wanted, you open the relevant rule file and add a line. The rule improves with use.

My best rules are 6 months of iterations condensed into 30 lines. No prompt can replicate that.

To inspect a rule quickly without leaving Claude Code:

!head -15 .claude/rules/email-drafting.md

Slash commands: turn any workflow into a shortcut

Simple rule: if a Markdown file exists in .claude/commands/, it becomes a slash command you can invoke instantly. The file is called process-meeting.md: you get /process-meeting. It's called weekly-summary.md: you get /weekly-summary.

What makes commands truly flexible is the wildcard argument. In your command file, you can use $ARGUMENTS as a placeholder. This lets you do:

/process-meeting latest
/process-meeting abc123-meeting-id

The command then knows whether to look for the latest meeting or a specific one by ID. Fireflies, Notion, Linear, whatever your stack: slash commands turn any repetitive operation into a deterministic shortcut.

Skills vs Commands: what's the actual difference?

This is the most common point of confusion among intermediate users.

Skills have trigger words in their description. When Claude processes a transcript and detects the words "action items," the action-tracker skill fires automatically. Without you having to ask.

An expert tip: if you start accumulating many similar skills, disable automatic invocation on the most specialized ones with disable-model-invocation: true in the skill file. This prevents Claude from using the wrong skill in an ambiguous case.

To build a complete agent team with skills on Claude Code, this article on the AI marketing team covers the full workflow.

Specialized agents: crystallize your recurring sub-agents

Sub-agents are becoming increasingly powerful. But if you keep using the same agent configurations over and over, it's time to crystallize them in .claude/agents/.

Each agent file defines its name, description, authorized tools, and most importantly: which model to use. That's where it gets interesting. For an agent that analyzes meeting transcripts, Haiku is more than enough. For a security auditor doing vulnerability analysis, you want Sonnet with more reasoning power.

I've launched 10 sub-agents in parallel to explore an entire codebase. Each one specialized on a single module. Unified report back. What takes an hour by hand.

An advanced tip: you can enable context: fork to let a skill run in its own context window, isolated from the main context. Ideal for heavy tasks that risk polluting your main session.

Settings.json and hooks: the safety net

The settings.json file in .claude/ controls what Claude can do on your machine. Authorized bash commands, accessible files, enabled tools.

Three permission levels:

• Allow all: Claude executes without asking (yolo mode, not recommended for sensitive projects)

• Ask first: Claude asks for confirmation before executing (the default mode)

• Never: certain commands are blocked no matter what

Hooks work at the settings.json level. A pre-tool-use hook runs before every tool call. Useful for protecting a .env file, logging actions, or checking a condition before a modification.

To see all your current settings:

!cat .claude/settings.json

The complete mental model: how everything fits together

Here's how all these pieces work together on a concrete example: a meeting processing workflow with the Fireflies.ai API.

• 1. The meeting ends. Fireflies captures the transcript automatically.

• 2. You run /process-meeting latest in Claude Code.

• 3. Claude loads the process-meeting.md command and calls the Fireflies API.

• 4. In the transcript, it detects action items: the action-tracker skill fires automatically.

• 5. The action items are structured according to the rules in .claude/rules/action-items.md.

• 6. The auto-follow-up skill takes over and drafts emails according to .claude/rules/email-drafting.md.

• 7. Everything is stored in Supabase. Settings.json authorized the network API calls beforehand.

A single 50-line CLAUDE.md file orchestrates all of this. It does nothing but point to the right pieces at the right time.

Where to start

If you've never configured your .claude folder, here's the priority order:

• First: a clean, short, router-oriented CLAUDE.md (no encyclopedia)

• Next: one or two rules for tasks you do often (email, commit messages, code review)

• Then: a slash command for your project's most recurring workflow

• Optional but powerful: a skill for patterns you want to automate

• Last: settings.json to lock down permissions based on your trust level

Start simple. Iterate. The .claude folder improves with use, not with planning.