Claude.Md Writer

---
name: claude-md-writer
description: Write the CLAUDE.md driver file for an AI agent — under 200 lines, operator identity, workflow order, hard rules, and nothing task-specific. Use when asked to write or fix a CLAUDE.md, set up agent instructions, create an instruction file, work out why an agent ignores its rules, slim down a bloated instruction file, or someone says 'my agent forgets everything I told it'. For the folder around it, see agent-folder-scaffold. For task-specific procedures, see skill-writer.
metadata:
  version: 1.0.0
---

# CLAUDE.md writer

The most important file in the folder. The agent reads it first, every single
session — and re-reads it on every message. That double fact drives every rule
here: it must carry everything stable, and it must stay **under 200 lines**,
because every line is billed on every turn.

The file is the compounding asset, not the output. Feed every lesson back into
it and the next run starts smarter than the last.

## Before you start

| Input | Why |
| --- | --- |
| Who the operator is — brand, domain, handles, author IDs | The agent acts on their behalf, by name |
| What the agent's one job is | One sentence; more than one job means more than one agent |
| The hard rules with their thresholds | "8 to 15 internal links" is a rule; "link well" is a wish |
| The proof numbers the brand may quote | Claims come from here, nowhere else |
| Known quirks — what has broken before | The cheapest lines in the file |

## Step 1 — Use the house skeleton

Every handbook's starter, filled in brackets:

```markdown
# [BRAND] <Agent Name>

You are the <role> for [BRAND] ([domain]), run by [NAME].
Your job: <one sentence>.

## Operator
- Name / site / handles / author IDs
- Business: what you do, the proof numbers you can quote
- Voice: [direct / academic / playful], 2 lines max

## Brand lock (never break)
- Logo path, colours (#hex), font, placement rules

## Core workflow
1. <skill-name>
2. <skill-name>  ← the ORDER is the instruction

## Rules that never break
- <rule with its number: "8-15 internal links per post">
- <rule with its reason where the reason prevents drift>

## Known quirks of this setup
- <anything that has broken before>
```

## Step 2 — Apply the one test to every line

**Does this belong in every session?** CLAUDE.md holds who you are, the workflow
order, and the rules that never break. Anything task-specific belongs in a skill,
so it loads only when needed — thirteen focused skills that load on demand beat a
3,000-line driver that makes every task slower, more expensive, and less accurate.

Treat the file as **an index that points to where details live**, not the details
themselves.

## Step 3 — Make rules enforceable

- Every rule carries its number: word counts, link counts, mention counts,
  author IDs. No number, no rule.
- Every claim the agent may make traces to the Operator section's proof numbers.
- Add the plan-mode guard from the token handbook: *"Do not make any changes
  until you are 95% sure what to build. Ask me questions until you reach that
  confidence."*

## Step 4 — Keep it alive

- `/init` drafts the first version by reading the folder; correct it rather than
  starting blank.
- `/memory` edits it live mid-session.
- **Save decisions, not conversations.** After a task, the key decisions land
  here — every stored decision is a paragraph never typed again.
- Trim on every visit. The 200-line ceiling is a budget, and budgets get audited.

## Output

```
# CLAUDE.md: <agent>   (<n>/200 lines)

Sections: Operator ✓ · Job (one sentence) ✓ · Brand lock ✓ ·
          Workflow (ordered) ✓ · Hard rules (all numbered) ✓ · Quirks ✓
Task-specific content: none — moved to skills: <list>
Plan-mode guard: present
Proof numbers: <n> claims, all in Operator section
```

## When it breaks

| What you see | What it means | The fix |
| --- | --- | --- |
| Agent ignores the rules | Rules buried mid-file in prose | Rules get their own section, numbered, near the top |
| File is 800 lines and growing | Task detail living in the driver | The one test: every-session content only; rest → skills |
| Every session starts expensive | The file is re-read per message | Under 200 lines; index, not encyclopedia |
| Agent invents claims | No proof-numbers section | Claims trace to Operator numbers, nowhere else |
| Same correction every session | Decisions not being saved back | Move 13: after the task, the decision goes in the file |
| Agent does jobs out of order | Workflow written as prose | Numbered workflow; the order IS the instruction |
| Wrong author/wrong brand details | Placeholders never filled | The bracket skeleton is a template, not a deliverable |

Never fix a misbehaving agent by adding another paragraph of prose instructions.
Diagnose which section failed — a rule without a number, a workflow without an
order, a decision never saved — and fix the structure.

## Rules

- **Under 200 lines, always**, because the file is re-read on every message and
  every line is a recurring cost.
- **Nothing task-specific**, because task detail belongs in skills that load on
  demand — that is the whole progressive-disclosure bargain.
- **Every rule carries its number**, because "do it well" cannot be enforced and
  "2,500–3,500 words" can.
- **Save decisions, not conversations**, because the file is the compounding
  asset — it is how next week starts smarter than this week.
- **One agent, one job, one file**, because a driver serving two jobs serves
  neither and grows without limit.

## Related skills

- **agent-folder-scaffold** — the folder this file drives; writing it is step 6.
- **skill-writer** — where everything task-specific goes instead.
- **token-budgeter** — moves 2 and 13 are this file's economics.
- **voice-file-builder** — the voice detail CLAUDE.md points to by name.