Structuring Claude Code Agents with CLAUDE.md and .claude/ Directory Patterns

Agent Directory Structure

The setup involves creating separate directories for each agent under ~/Documents/. The example shows five agents: planner (executive function, routing, accountability), content (content pipeline), youtube (YouTube production), life (personal domains), and control-center (dashboard, database, API).

Each agent follows this template structure:

agent-name/
├── CLAUDE.md # Identity + mission + capabilities
├── .claude/
│   ├── rules/ # Auto-loaded context (always-on)
│   └── skills/ # On-demand workflows
├── inbox/ # Input from other agents
├── outputs/ # Generated output
└── archive/ # Nothing gets deleted without archiving

Rules vs Skills Distinction

The .claude/rules/ files are loaded automatically at the start of every session. Claude reads them as part of its context window. This is where you put things the agent needs to know always — its scope, business context, how it should behave.

The .claude/skills/ files are on-demand. They only load when you invoke them with /skill-name. This is where you put specific workflows like multi-step processes, templates, structured routines.

Rules files load into your context window at session start and stay there. Claude Code uses prompt caching so repeated content isn't billed at full price each turn, but large rules files still increase context pressure and can cause response degradation. With skills, only the name and description live in context by default; the full workflow loads on-demand, either when you call it or when Claude decides it's relevant.

Rule of Thumb

• Rules (always-on): Scope boundaries, business context, routing logic, naming conventions — things that affect every decision
• Skills (on-demand): Step-by-step workflows, templates, batch operations. Things you do occasionally (Note: skill descriptions are always in context so Claude knows what's available; only the full content is on-demand)

CLAUDE.md Content

The CLAUDE.md file should be kept under 120 lines and covers:

• Identity (2-3 lines): who this agent is and what it does
• Current phase (2-3 lines): what we're working on right now
• Core capabilities (10-15 lines): what skills are available, what it can do
• Key locations (10-15 lines): file paths it needs to reference
• What's been built (10-20 lines): history of completed work
• What's next (5-10 lines): immediate priorities
• Principles (5-10 lines): behavioral guardrails

Example Rules Structure

For a Planning Agent, the .claude/rules/ directory contains numbered files that control load order:

.claude/rules/
├── 01-business-context.md # Revenue model, positioning, target customers
├── 02-agent-ecosystem.md # All agents, their missions, how they connect
├── 03-roadmap.md # Current phase, milestones, exit criteria
├── 04-content-architecture.md # Content channels, pillars, workflow
├── 05-daily-routine.md # Schedule, idea filtering, anti-distraction rules
├── 07-godin-strategy.md # Marketing principles, milestone tracking
├── 08-control-center.md # CLI tools reference, DB schema
├── 98-end-of-session.md # Ritual: update roadmap, capture knowledge
└── 99-content-capture.md # Auto-extract content signals from every session

Agent Communication

The agents don't call each other directly. They coordinate through:

• SQLite database: Source of truth for tasks, content pipeline state, sessions, metrics
• Inbox files: When one agent needs to hand context to another, it drops a markdown file in the target's inbox/
• API endpoints: Dashboard reads