Building Your Agents

A reusable brief, not a piece of engineering.

An agent is a set of instructions and files you reuse. If you can write a good brief for a contractor, you can write one. Most tasks do not need one at all.

Craft guidanceShortcut editorial, reviewed 9 Oct 2026

In 30 seconds

One agent, one job
Write down what it must not do
Say what sources it may use
Fix the output format
Give it a checklist to run on its own work

What goes into one

Role and purpose: One sentence. If it needs two, it is two agents.
Context files: What it reads every time. See the nine files.
Reference files: Material for this task only.
Constraints: What it must not do or change.
Source rules: What it may rely on and how to cite it.
Output format: The same shape every time, so you can compare runs.
Validation steps: Checks it runs before answering.
Permissions: What it can read and change. Start with read-only.

One agent or several

One: The task is a single job with one kind of output.
Split it: One part generates and another checks, or the context for each part is different.
None: You will do it once, or explaining it takes longer than doing it.

Quality gates

It lists its assumptions
It cites where each fact came from
It says what it could not do
A person reviews before anything is shared

Example agents

Research assistant
Organises notes and transcripts into candidate themes.
Its guard railEvery theme lists the quotes behind it. No theme without evidence.
UX critique agent
Gives a first-pass critique against a stated goal.
Its guard railEach finding is typed: standard, convention or opinion.
Design system agent
Checks a design against your tokens and components.
Its guard railIt may only name tokens and components that exist in the file you gave it.
Handoff agent
Drafts specs and acceptance criteria from a finished design.
Its guard railIt documents what was designed. Anything undefined is listed as a question.
Accessibility review agent
Flags likely issues for a human to test.
Its guard railIt cites the criterion for each claim and never declares a design accessible.
Content review agent
Checks copy against your tone and terminology.
Its guard railIt quotes the rule it applied from your guide.

Agent template

AGENT TEMPLATE

Purpose
  One sentence: what this agent is for.

Inputs
  What you will give it each time.

Context
  The files it should always read first.

Constraints
  What it must not do or change.

Sources
  What it may rely on, and how it must cite it.

Output format
  The shape of what comes back.

Validation checklist
  What the output must pass before anyone uses it.

Go deeper in Shortcut

What goes into one

Role and purpose: One sentence. If it needs two, it is two agents.
Context files: What it reads every time. See the nine files.
Reference files: Material for this task only.
Constraints: What it must not do or change.
Source rules: What it may rely on and how to cite it.
Output format: The same shape every time, so you can compare runs.
Validation steps: Checks it runs before answering.
Permissions: What it can read and change. Start with read-only.

Example agents

Research assistant
Organises notes and transcripts into candidate themes.
Its guard railEvery theme lists the quotes behind it. No theme without evidence.
UX critique agent
Gives a first-pass critique against a stated goal.
Its guard railEach finding is typed: standard, convention or opinion.
Design system agent
Checks a design against your tokens and components.
Its guard railIt may only name tokens and components that exist in the file you gave it.
Handoff agent
Drafts specs and acceptance criteria from a finished design.
Its guard railIt documents what was designed. Anything undefined is listed as a question.
Accessibility review agent
Flags likely issues for a human to test.
Its guard railIt cites the criterion for each claim and never declares a design accessible.
Content review agent
Checks copy against your tone and terminology.
Its guard railIt quotes the rule it applied from your guide.

AGENT TEMPLATE Purpose One sentence: what this agent is for. Inputs What you will give it each time. Context The files it should always read first. Constraints What it must not do or change. Sources What it may rely on, and how it must cite it. Output format The shape of what comes back. Validation checklist What the output must pass before anyone uses it.