| name | dot-folder-architecture |
| description | Set up, scaffold, or audit a .claude/ folder structure for any project using Claude Code. Use this skill whenever a user wants to initialise a new Claude Code project, add structure to an existing one, or asks how to organise their Claude instructions, agents, rules, context, schemas, or memory. Also triggers when a user says their Claude Code setup feels brittle, inconsistent across sessions, or impossible to hand off to another operator. The skill produces a ready-to-commit folder layout with starter files for every subdirectory.
|
.claude/ Folder Architecture
A structured, git-committed workspace that separates what Claude knows,
how Claude behaves, and where a workflow is right now — so Claude Code
produces consistent, auditable, handoff-ready results across sessions,
operators, and projects.
The Core Principle
Most Claude Code setups fail at scale because everything lives in one file.
Instructions, domain knowledge, session state, agent definitions — all
piled into a growing CLAUDE.md that Claude re-interprets differently every
session.
The fix is separation of concerns across three questions:
| Question | Folder(s) |
|---|
| How should Claude behave? | rules/ |
| What should Claude know? | context/, schemas/ |
| Where is the workflow right now? | memory/ |
Everything else (commands/, agents/, skills/, protocols/) layers
on top of this foundation.
Folder Layout
your-project/
├── CLAUDE.md ← entry point (committed)
├── CLAUDE.local.md ← personal overrides (gitignored)
└── .claude/
├── STRUCTURE.md ← what each folder is for
├── settings.json ← shared permissions (committed)
├── settings.local.json ← personal permissions (gitignored)
├── settings.env.json ← env-aware config (committed)
├── commands/ ← human-triggered slash commands
├── agents/ ← subagent persona definitions
├── rules/ ← behavioural instructions
├── context/ ← persistent domain knowledge
├── schemas/ ← output shape definitions
├── skills/ ← auto-invoked workflows
├── protocols/ ← agent-to-agent contracts
└── memory/ ← runtime state (gitignored)
Step-by-Step Setup
Step 1 — Create the folder structure
mkdir -p .claude/{commands,agents,rules,context,schemas,skills,protocols,memory}
touch CLAUDE.md CLAUDE.local.md
touch .claude/STRUCTURE.md
touch .claude/settings.json .claude/settings.local.json .claude/settings.env.json
Step 2 — Write CLAUDE.md
CLAUDE.md is the first file Claude Code reads. Keep it short.
It should contain: project purpose, stack, and pointers to the
relevant .claude/ subfolders for the task at hand.
# [Project Name]
## What this project is
[One paragraph — purpose, stack, primary language.]
## Key conventions
- Rules: .claude/rules/
- Domain knowledge: .claude/context/
- Output specs: .claude/schemas/
- Slash commands: .claude/commands/
- Memory (current state): .claude/memory/state.json
## Read first for [task type]
- Code tasks: .claude/rules/code-style.md
- Content tasks: .claude/rules/brand-voice.md + .claude/context/
- Deployments: .claude/commands/deploy.md
Step 3 — Populate settings.json
Define which tools Claude Code can use and which paths it can write to.
{
"tools": {
"bash": true,
"file_write": true,
"allowed_write_paths": ["src/", "docs/", ".claude/memory/"]
},
"safety": {
"require_confirmation_before_deploy": true,
"protected_paths": [".env", "secrets/"]
}
}
Step 4 — Populate settings.env.json
Prevents agents from publishing, deploying, or notifying in the wrong
environment.
{
"dev": { "publish": false, "notify": false, "log_level": "verbose" },
"staging": { "publish": false, "notify": true, "log_level": "standard" },
"prod": { "publish": true, "notify": true, "log_level": "minimal" }
}
Step 5 — Add .gitignore entries
.claude/settings.local.json
.claude/memory/
CLAUDE.local.md
What Goes in Each Folder
rules/ — How Claude behaves
Modular behavioural instructions. Slow-changing. Committed to git.
rules/
├── code-style.md ← formatting, naming, test coverage
├── brand-voice.md ← tone, vocabulary, banned phrases
├── api-conventions.md ← endpoint patterns, error handling
└── funnel-map.md ← CTA rules, stage logic (content projects)
What belongs here: anything that tells Claude how to act
regardless of what task it's doing.
What does not belong here: facts about your business or domain
(that's context/), output shapes (that's schemas/), or anything
that changes per-run (that's memory/).
context/ — What Claude knows
Persistent project knowledge. Domain grounding, not behavioural
instruction. Updated when the project's domain evolves.
context/
├── brand-voice.md ← if brand tone is complex enough
├── topics.md ← content taxonomy, topic hierarchy
├── sources.md ← approved sources, trust tiers
└── audience.md ← who we're building for
What belongs here: anything Claude needs to know to do good
work — not how to behave, but what the world of this project looks like.
schemas/ — What Claude must produce
Output shape definitions. The contract between an agent and whatever
consumes its output. Machine-readable where possible.
schemas/
├── brief-format.md ← human-readable spec
├── newsletter-item.json ← structured output shape
├── research-summary.json ← agent output format
└── task-handoff.json ← inter-agent payload shape
Rule: any agent that produces structured output must reference a
schema in its definition. Never let output shape be implicit.
commands/ — Human-triggered actions
Each .md file becomes a /project:filename slash command in
Claude Code. Use for actions that should only run when a person
explicitly asks.
commands/
├── review.md → /project:review
├── fix-issue.md → /project:fix-issue
└── deploy.md → /project:deploy
Each file should state: purpose, required inputs, expected output,
and preconditions.
agents/ — Subagent personas
Isolated agents with their own role, instructions, and boundaries.
Agents do not share state unless explicitly passed via protocols/.
agents/
├── code-reviewer.md
├── security-auditor.md
└── research-agent.md
Each agent file must declare:
- Role — what it is responsible for
- Scope — what it can and cannot do
- Input — what it expects to receive
- Output — what it must produce (reference a schema)
- Trigger — when it auto-activates (if applicable)
skills/ — Auto-invoked workflows
Claude Code triggers these automatically when conditions are met.
Each skill is a folder containing a SKILL.md.
skills/
├── index.md ← trigger map: condition → skill
├── security-review/
│ └── SKILL.md
└── deploy/
└── SKILL.md
skills/index.md must exist and must explicitly map conditions to
skills — triggering logic should never be implicit.
| Condition | Skill |
|----------------------------------|-------------------|
| Any file in /auth modified | security-review |
| PR targeting main branch | security-review |
| deploy.md command invoked | deploy |
protocols/ — Agent-to-agent contracts
How agents hand off work to each other. Essential for multi-agent
orchestration.
protocols/
├── handoff-format.json ← source-of-truth payload shape
└── input-output-spec.md ← prose explanation for anyone writing agents
memory/ — Runtime state only
The only folder that changes between runs. Gitignored. Contains
whatever agents need to resume a workflow or avoid repeating completed
steps.
memory/
├── state.json ← current pipeline state, updated per run
└── run-log.md ← append-only log of completed actions
Rules:
- Keep files small and structured
state.json must be readable in isolation — an agent should know
exactly where a workflow left off from this file alone- Never put instructions or knowledge here — those belong in
rules/
or context/
Audit Checklist
Use this when reviewing an existing .claude/ setup:
□ CLAUDE.md is short and points to subfolders — not a dump of all instructions
□ rules/ contains only behavioural instructions (not domain facts)
□ context/ contains only domain knowledge (not how-to instructions)
□ memory/ is in .gitignore
□ settings.local.json is in .gitignore
□ Every agent in agents/ references a schema in schemas/
□ skills/index.md exists and lists all trigger conditions explicitly
□ state.json in memory/ is readable standalone (not dependent on context)
□ No instruction, rule, or fact is duplicated across multiple files
Folder Purpose at a Glance
| Folder | Answers the question | Changes how often |
|---|
rules/ | How should Claude behave? | Rarely |
context/ | What should Claude know? | Occasionally |
schemas/ | What must Claude produce? | Occasionally |
commands/ | What can a human trigger? | Rarely |
agents/ | Who does what autonomously? | Occasionally |
skills/ | What triggers automatically? | Rarely |
protocols/ | How do agents talk to each other? | Rarely |
memory/ | Where is the workflow right now? | Every run |
.gitignore Reference
# Claude Code — personal and runtime files
.claude/settings.local.json
.claude/memory/
CLAUDE.local.md
Built by Yuri Vonchitzki — used across
Ninjabot client builds. Part of the CALMER framework for calm,
deliberate AI adoption.
