# Agent blueprint

Use this file to design your next agent before you ask Codex to build it. The meeting agent is only the example. The same seven answers work for any job: inbox triage, proposal drafting, invoice checks, candidate screening, weekly reporting.

Fill in each section in plain English. Short, specific answers beat long, vague ones. Then give the finished file to Codex with the prompt at the end.

## 1. The one job

One sentence: when the agent receives ___, it produces ___ for ___.

- Meeting example: when it receives meeting notes or a transcript, it produces a follow-up pack for the people who attended.
- Your agent:

If you need the word "and" twice, you probably have two agents. Start with one.

## 2. Name

Lowercase with underscores, describing the job, not a persona.

- Meeting example: `meeting_followup`
- Your agent:

## 3. What it receives

List the real inputs, in the messy form they actually arrive.

- Meeting example: raw transcripts, typed notes, recording summaries. Speakers are sometimes unlabeled.
- Your agent:

## 4. What good looks like

Describe the output section by section, in order of importance. Say how long each part may be. This is the part most people skip, and the part that decides quality.

- Meeting example: action items table first (action, owner, deadline, source quote), then commitments, decisions, needs attention, a summary of no more than five bullets, and a follow-up under 90 words.
- Your agent:

## 5. What it must never do

The rules that protect you. Be concrete.

- Never invent facts, names, numbers, owners or deadlines. Mark missing information instead.
- Never send, publish, pay, delete or change anything without approval.
- Your agent's specific risks:

## 6. How it handles gaps

What should it do when information is missing, unclear or contradictory? Flag it, ask, or stop?

- Meeting example: write UNASSIGNED or NO DEADLINE and list the item under "Needs attention".
- Your agent:

## 7. Before and after

What happens immediately before this job, and what should happen immediately after it? This is where you connect tools later. Do not connect them on day one.

- Meeting example. Before: the meeting is recorded and transcribed. After: tasks go to the right people, the client record is updated, a Gmail draft is ready to review, and a pre-meeting brief is ready before the next call.
- Your agent. Before:
- Your agent. After:

## Test cases

Collect two or three real examples of the input before you build. Include one that is messy or incomplete. Write down what a correct result must catch in each, so you can judge the agent against something other than a feeling.

1.
2.
3.

## The build prompt

Paste this into a new Codex chat inside your project, with this completed file attached:

> Create a reusable custom Codex subagent from the attached agent-blueprint.md. Save it as a personal agent at `~/.codex/agents/<name>.toml`. Write the required name, description and developer_instructions. The description should say exactly when to use this agent. The instructions should cover the job, inputs, the output structure in order, every never-do rule and how to handle gaps, and end with a short quality check the agent runs before answering. Set sandbox_mode to "read-only" unless the blueprint says the agent must write files. Do not create a Skill or AGENTS.md instead of the custom agent. When finished, validate the configuration and show me the full file and where you saved it.

## The improvement loop

1. Run the agent on your test cases in a fresh chat.
2. Compare the result with what it had to catch.
3. Tell Codex what to change in the agent itself, not in the chat: "Update my `<name>` agent so that … Keep all existing rules."
4. Run the same test again in a new chat. Keep going until two runs in a row need no correction.