Your first agent.md
A “soul file” — define a specialist. One file, one role.
What an agent.md is
CLAUDE.md (Foundations 01) is the project-level instruction file. It applies to every session. An agent.md is a role-level file. It defines a single specialist — what it does, when it fires, what it can decide.
Some operators call these “soul files” because each one captures the soul of a specific role: a code reviewer, a design critic, a legal first-pass, a content drafter, a chief-of-staff. The file lives at 05-Agents/<NAME>.md by convention, but the location matters less than the structure.
The rule that makes agent.md files work: one role per file. Don’t mix domains. A design specialist is one file. A code reviewer is another file. A legal reviewer is a third. Trying to combine them produces an agent that’s vague at everything and excellent at nothing.
The story
I started with one agent. Then two. Then six. Then I tried fourteen and realized fourteen agents made me slower, not faster, because the routing overhead exceeded the specialization payoff.
The lesson took about a year of running multiple ventures on Claude Code: a small set of named, scoped specialists is more reliable than a sprawling cast of agents that don’t know their lane.
But the small set doesn’t happen by default. By default, you have one agent (Claude itself) and you re-explain context every session. Every “please match the existing visual style.” Every “use Netlify Forms not a custom endpoint.” Every “don’t commit to main without my approval.” The same instructions, conversation after conversation.
The first agent.md you write replaces a category of those instructions. You define PIXEL once — its scope, its triggers, its authority, its tools — and from then on, when you say pixel: audit the spacing, the agent loads with all of that context already in place.
That’s the leverage. Every subsequent agent.md adds another category of removed friction.
Three ways agent.md goes wrong
Most first attempts fall into one of these. Hover any card to see the diagnosis.
The all-in-one agent
Vague triggers
Authority-less role
The fix in all three cases is the same shape: specificity that the agent can grip on. Specific scope, specific triggers, specific authority. Vague specialists don’t fire reliably.
The first-decision test
The best diagnostic for whether your agent.md is specific enough: imagine a fresh Claude session activates as this agent and receives a realistic first message. What does the agent do?
If you can answer that question with a specific action — “reads app/labs/labs.css, runs the spacing audit on the lesson page, drafts a list of inconsistencies, surfaces them as a comment” — your agent.md is concrete enough.
If your answer is vague — “reviews the design, gives feedback” — the file is too generic to fire reliably.
Read this agent.md.
A fresh Claude session has just been activated as this agent.
The operator types: <REPLACE WITH A REALISTIC FIRST MESSAGE>.
Walk through what the agent does, step by step.
- What does it default to?
- Which file or tool does it touch first?
- Where does it stop and ask vs continue on its own?
If any step is unclear from the agent.md alone, mark the gap.
The goal: every step should map to a specific line in the file.Forces the agent.md to map every part of the agent's behavior to a specific line in the file.
A good agent.md should produce a clean step-by-step answer to this prompt. Every step traces to a specific line in the file. Any step that doesn’t trace is a gap.
Annotated transcript
The conversation that produces a working agent.md from a single recurring frustration. Click any pinned annotation under an agent reply to expand the “why this turn matters” commentary.
Five operator turns, four agent turns. Result: a 38-line agent.md and an updated routing table.
- operator
Every time we have a design question I have to re-explain my visual style, my brand colors, my type system. Can we just have a design specialist?
- agent
Yes. We need an agent.md file at
05-Agents/PIXEL.md. Three things to nail down before you write it: what's its scope, what triggers it, and what authority does it have? - operator
Scope: visual design across the labs site, the main site, and any new pages. Catches design drift, AI-slop visual patterns, accessibility gaps.
- agent
Good — that's specific enough. "Visual design" alone would be too broad. Naming the surfaces (labs, main site, new pages) and naming the failure modes (drift, AI-slop, a11y) gives the agent something to grip on.
Next — triggers. What would you actually type to invoke it?
- operator
Things like "design review", "audit the spacing", "check the visual hierarchy". Or just "pixel:" as a prefix.
- agent
Good. Three trigger types — explicit prefix (
pixel:), specific phrases (audit the spacing,check the visual hierarchy), and file-path matches (any edit to/app/labs/labs.csscould auto-route here). I'll list all three.Authority — what can PIXEL decide on its own?
- operator
It can flag issues and draft fixes. It can edit CSS files. It cannot push to main and cannot decide brand-level questions like changing the color palette.
- agent
Got it. Authority L3 — can edit and propose, cannot ship without operator review.
Last — tools. What does PIXEL need access to that other agents don't?
- operator
Read access to the styles, the components, the design tokens. Write access to CSS only. Browser access to test live pages.
- agent
Drafted at
05-Agents/PIXEL.md. 38 lines. Includes scope (3 surfaces, 3 failure modes), triggers (1 prefix + 4 phrases + 2 file-path patterns), authority (L3 with explicit can-and-cannot), and tools (read scope + write scope + browser). Saved.Updated
CLAUDE.mdrouting table to add PIXEL with the trigger phrases. Test it with: "pixel: audit the spacing on /labs/lessons/first-claude-md".
The four fields every agent.md needs
Every agent.md must answer four questions. Skip any of them and the agent is too vague to fire reliably.
| Field | Question it answers | Good | Bad |
|---|---|---|---|
| Scope | What domain does this agent own? | “Visual design across labs, main site, and new pages. Catches drift, AI-slop, and a11y gaps.” | “Design and visual stuff.” |
| Triggers | What activates this agent? | Prefix pixel: · phrases “audit the spacing”, “check the visual hierarchy” · file edits to *.css | “Use for design questions.” |
| Authority | What can it decide vs escalate? | “L3 — can edit CSS, propose changes. Cannot push to main. Cannot change brand-level palette.” | “Reviews things and helps.” |
| Tools | What does it need access to that others don’t? | “Read: app/**. Write: **/*.css. Browser to test live pages.” | “Standard tools.” |
The pattern across all four: specific enough that a fresh agent could load this file and know what to do. If the answer requires the operator to clarify, the file is incomplete.
The skeleton — copy-paste this and fill in your values
A working agent.md skeleton. Replace bracketed values with your real ones, save at 05-Agents/<NAME>.md, and add the agent to your CLAUDE.md routing table.
---
type: agent
agent-id: <name-slug>
codename: <DISPLAY_NAME>
team: <which team or surface>
role: <one-sentence role description>
authority: <L1 | L2 | L3 | L4 | L5>
triggers: ["<prefix>:", "<phrase>", "<phrase>"]
tools: ["<tool-1>", "<tool-2>", "<tool-3>"]
companies: ["<venture-1>", "<venture-2>"]
status: active
---
# <DISPLAY_NAME>
**ID:** <name-slug>
**Team:** <team>
**Role:** <one-sentence role>
**Authority Level:** <L1-L5>
## Scope
[2-3 sentences. Name the surfaces this agent owns. Name the failure
modes it catches. Be specific enough that a fresh agent could draw
the boundary between what's in scope and what's out.]
## Activation Triggers
- Prefix: `<prefix>:`
- Phrases:
- "<specific phrase 1>"
- "<specific phrase 2>"
- File-path patterns:
- <glob pattern that auto-routes work to this agent>
## Primary Tools & MCPs
- <tool 1 — what it does for this agent>
- <tool 2>
- <tool 3>
## Responsibilities
1. <Specific responsibility 1>
2. <Specific responsibility 2>
3. <Specific responsibility 3>
## Authority — what this agent can/cannot do
**Can decide on its own:**
- <Specific action>
- <Specific action>
**Must draft and surface for operator approval:**
- <Specific action>
**Must escalate (do not act):**
- <Specific action>
## Companies/Surfaces Served
- <venture or surface 1>
- <venture or surface 2>
## Related Agents
- [[<other agent>]] — <how they relate>
You don’t need every section. A solo specialist might be 25-40 lines. A complex multi-domain one might be 80-120. Length is a function of complexity, not effort. Aim for the shortest file that answers all four questions.
Prompt kit
Three prompts for writing and maintaining agent.md files. Save in your CLAUDE.md or a personal snippets file.
Read this agent.md.
A fresh Claude session has just been activated as this agent.
The operator types: <REPLACE WITH A REALISTIC FIRST MESSAGE>.
Walk through what the agent does, step by step.
- What does it default to?
- Which file or tool does it touch first?
- Where does it stop and ask vs continue on its own?
If any step is unclear from the agent.md alone, mark the gap.
The goal: every step should map to a specific line in the file.Read my agent.md trigger list.
For each trigger, give me 3 example operator messages that should
fire this agent — and 1 message that's adjacent but should NOT fire it.
If a trigger doesn't have clear positive AND negative examples,
it's too vague to be reliable. Rewrite it.Read my agent.md authority section.
List 5 realistic actions this agent might consider taking. For each,
say whether the agent should:
- DECIDE — proceed without checking
- DRAFT — propose, await operator approval
- ESCALATE — refuse, route to operator or chief-of-staff
If any action is ambiguous, the authority section needs more detail.Apply this — write your first agent.md right now
25-minute exercise. Pick one role you re-explain. Define it. Test it. Iterate.
Build your first agent.md
Each step takes ~5 minutes. Progress saves automatically.
- 01Pick one role you re-explain to Claude over and over.Visual design, code review, legal first-pass, content drafting — anything you've explained 3+ times.
- 02Drop the skeleton from this lesson into 05-Agents/<NAME>.md.Replace placeholders with your real values. ~15 minutes.
- 03Apply the first-decision test. Imagine a realistic first message; walk what the agent does.If any step is unclear from the file alone, the file is too vague. Iterate.
- 04Update CLAUDE.md to add the new agent to your routing table.List its trigger words. Reference its authority level. Two lines max.
- 05Test it: send a real message that should fire the agent.Watch whether the chief-of-staff routes correctly. If it doesn't, your triggers are wrong — go back to the file.