# Agent Configuration Cheat Sheet

**CLAUDE.md vs SOUL.md vs SKILL.md — When to Use Each**

---

## At a Glance

| File | What It Is | Equivalent Of | When to Create |
|------|-----------|---------------|----------------|
| **CLAUDE.md** | Project configuration | A job description | First. Every project needs one. |
| **SOUL.md** | Agent personality | A personality profile | When the agent represents your brand |
| **SKILL.md** | Task-specific knowledge | A training manual | When you repeat a workflow more than twice |

---

## CLAUDE.md — The Job Description

**Where it lives:** Project root directory
**Scope:** One project (each project gets its own)
**Works with:** Claude Code

### Must-Have Sections:
1. **What This Is** — One specific paragraph describing the project
2. **File Conventions** — Exact formats for every file the agent touches
3. **Key Principles** — Judgment guidelines for ambiguous situations
4. **Security Rules** — What to never commit or expose

### Nice-to-Have Sections:
5. Available Skills — Table of slash commands
6. Key Workflows — Numbered steps for core processes
7. Companion Docs — References to SOUL.md and STYLE.md
8. Build Commands — Install, test, build, deploy
9. Division of Labor — What agent does vs. what human does

### Quick Win:
Write sections 1, 2, and 3. That alone changes agent behavior dramatically.

---

## SOUL.md — The Personality

**Where it lives:** Project root or home directory
**Scope:** Agent-wide (consistent across all projects)
**Works with:** Any LLM, OpenClaw agents

### Must-Have Sections:
1. **Core Identity** — Who the agent IS, not what it does
2. **Communication Style** — Tone, length, vocabulary
3. **Anti-Patterns** — What the agent should never sound like

### Nice-to-Have Sections:
4. Values — Specific beliefs that guide judgment
5. Opinions — Positions the agent holds and defends
6. Boundaries — Topics it won't engage on
7. Context About Owner — Industry, size, constraints

### The Test:
Can someone reading your SOUL.md predict the agent's positions on topics it hasn't seen before? If not, be more specific.

---

## SKILL.md — The Training Manual

**Where it lives:** `.claude/skills/[skill-name]/` folder
**Scope:** Per-task or per-workflow
**Works with:** Claude Code, OpenAI Codex, any MCP-compatible agent

### Folder Structure:
```
.claude/skills/my-skill/
├── SKILL.md          ← Core instructions (YAML header + markdown body)
├── scripts/          ← Optional executable code
├── references/       ← Optional documentation
└── assets/           ← Optional templates and materials
```

### YAML Header Fields:
- `name` — Skill identifier
- `description` — One-line summary (loaded always, ~50 tokens)
- `triggers` — Slash commands or keywords that activate it
- `tags` — Categories for organization

### Token Economics:
- **Metadata only:** ~50-100 tokens per skill (always loaded)
- **Full instructions:** Up to 5,000 tokens (loaded on demand)
- **Resources:** Varies (loaded during execution only)

### The Rule:
Any workflow you do more than twice should be a skill.

---

## The Layering

```
┌─────────────────────────────────┐
│         SOUL.md                 │  ← WHO the agent is
│   (personality, values, voice)  │     Consistent everywhere
├─────────────────────────────────┤
│         CLAUDE.md               │  ← HOW the agent works here
│   (project config, conventions) │     Different per project
├─────────────────────────────────┤
│         SKILL.md (×N)           │  ← WHAT the agent knows
│   (task knowledge, workflows)   │     Loaded on demand
└─────────────────────────────────┘
```

**Start with CLAUDE.md. Add SKILL.md for repeated workflows. Add SOUL.md when voice matters.**

---

*From Blue Octopus Technology — blueoctopustechnology.com*
*Read the full guide: blueoctopustechnology.com/blog/claude-md-vs-soul-md-vs-skill-md*