# The anatomy of an agent

Design the agent before you build it. Answer five questions. Then write seven files.
If you cannot answer a question, you are not ready to build.

---

## Part 1 — Five questions

### 1. Purpose — who is it for, and what job does it do?
- Name the person, not the persona. "A delivery manager on a discovery with no researcher" beats "users".
- Name one job. If it needs "and", it may be two agents.
- Name the seat it fills, and the seat it does not claim. (UCD Writer writes. The content designer still decides.)

### 2. Boundaries — what must it never do?
- List refusals as plain sentences. "Never writes to a tracker without a yes."
- List what it must never invent: quotes, metrics, users, sources.
- List data it must never keep: personal data, raw transcripts after the session.

### 3. What it touches — tools and connections
- One row per tool. Read, write, or both. Scope written in full.
- Default to read-only. Every write is a decision, not a feature.
- Say what happens when a tool is not connected. The agent must still work, with less.

### 4. When a human steps in — approval gates
- Put a gate before every write to the outside world.
- Put a gate before every stage change.
- Say what the human sees at the gate: a summary, the evidence, the exact change, a yes or no.

### 5. How you know it is working — evaluation
- A fixed set of test inputs. Real enough to fail on.
- A pass mark per test, judged against a named standard.
- A human reviewer for anything that needs judgement.
- Run before every release. Record the score.

---

## Part 2 — Seven components

| File | Answers | Contents |
|---|---|---|
| `instructions.md` | 1, 2 | Role, voice, tone, refusals, two worked examples |
| `skills/` | 1 | One file per skill: inputs, steps, outputs, evidence rule, gate |
| `tools.md` | 3 | Every connection with read/write scope and fallback |
| `manifest.md` | 3 | Which skill uses which tool. No gaps, no guesses |
| `guardrails.md` | 2, 4 | Each risk, its control, its owner, sign-off |
| `memory.md` | 2 | What is kept, where, how long, who agreed it |
| `evals/` | 5 | Test inputs, expected outputs, pass marks, last score |

---

## Part 3 — How it ships

One zip per agent. Bought once, downloaded straight away.

| You get | What it means |
|---|---|
| The seven components | Every file above, in plain markdown |
| Adapters | One-file hooks for Claude Code, Cursor, AGENTS.md tools, and chat bots |
| Samples | GOV.UK-style inputs so the first run works on day one |
| Your own keys | Runs in the AI tool you already pay for. Nothing to host. |

Unzip into a repo. Say the trigger phrase. Approve each stage.
The intelligence is in the stages and the standards, not the interface.