The language
An instruction is ordinary writing. A few small additions let you say exactly what matters, so people can review it and every agent understands it the same way. This tour shows them one at a time, with the same example throughout: an assistant that plans someone's day.
Start with plain writing
Most of an instruction is prose: what the agent is for and how it should work. A short header at the top gives the document a title and a version. Notes for people, like who wrote it and why it changed, go at the very end, and the agent never receives them.
---
spec: "1"
title: Morning assistant
version: "1.0.0"
---
# Morning assistant
Prepare a useful daily brief.
MUST[status]: keep tentative appointments tentative.
BECAUSE: an invitation is not a commitment.
---
authors: [Alex]
history:
- summary: Preserve appointment status.
sources:
- { title: Team guidance, uri: ./team.md } Rules
A line that starts with one of five words is a rule. The word says how strong it is, and an optional name in square
brackets lets people refer to it. BECAUSE: on the next line gives the reason, which helps an agent
apply the rule sensibly.
| Word | What it means | For example |
|---|---|---|
MUST | A requirement | ask Alex before changing an invitation. |
SHOULD | A considered default | keep the daily brief under 150 words. |
MAY | An allowed choice | suggest a focus task when time is available. |
NEVER | A prohibition | reveal a private event to another person. |
SHOULD NOT | A discouraged action | plan around it as a confirmed commitment. |
MUST[approval]: ask Alex before changing an invitation.
BECAUSE: calendar changes affect other people. A rule can also say when it applies, in brackets after its word:
SHOULD NOT (if an invitation is tentative): plan around it as a confirmed commitment.
BECAUSE: the attendee has not accepted yet. Policies and guardrails
Rules that belong together can be grouped into a policy with its own title, so they are reviewed, shared and replaced as one. A guardrail marks a boundary that should stand out to anyone reading.
:::policy{id=calendar title="Calendar policy"}
MUST[approval]: ask Alex before changing an invitation.
BECAUSE: calendar changes affect other people.
SHOULD[brief]: keep the daily brief under 150 words.
NEVER[privacy]: reveal a private event to another person.
::: :::guardrail{id=calendar-changes title="Calendar changes"}
Never send, delete, or move an invitation without the owner's approval.
::: Rich instructions
Short rules are not always enough. You can add conditions, an example of what good looks like, and the shape of the answer you expect. Each part is marked for what it is, so the agent can tell guidance from an example, and a reader sees them laid out clearly.
:::policy{id=planning title="Planning guidance"}
MUST[status] (if an invitation is tentative): preserve its tentative status.
BECAUSE: an unanswered invitation is not a commitment.
SHOULD[brief]: keep the daily brief under 150 words.
BECAUSE: the owner reads it on a phone.
NEVER[privacy]: reveal private event details to another person.
:::
:::example{title="Preserve the uncertainty"}
Your 09:00 catch-up is tentative. The 11:00 review is confirmed.
:::
:::output{response-format=markdown title="Daily brief"}
Use commitments, one focus task, and open decisions.
::: Tools
An instruction can name the tools an agent may use, such as a calendar connected over MCP, and say which of its actions are allowed. Here the assistant may read events and availability (events.list, availability.read) but never delete an event (events.delete).
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
::: Skills
A skill is a reusable way of doing one task, written as steps. Write it once, give it a name, and refer to it wherever it is needed. This one is “Prioritize the day”: choose one useful, achievable focus task.
:::skill{id=prioritize title="Prioritize the day"}
Choose one useful, achievable focus task.
1. Review commitments and available focus time.
2. Choose one useful, achievable task.
3. Explain why it is a good first priority.
:::
Use :skill[Prioritize the day]{ref=#prioritize}. People
Instructions often depend on people: who owns a decision, who must approve a change. Declare a person once, and rules can refer to them by name. Anyone reading sees who is meant, and tools can link to them.
::person{id=owner title="Alex" role=owner src="https://example.org/people/alex"}
MUST[approval]: ask :person[Alex]{ref=#owner} before changing an invitation.
BECAUSE: calendar changes affect other people. Putting it together
Here is the whole assistant in one file: its header, its purpose, a rule, the calendar it may use, a skill, a small workflow and the notes for people. Open the editor to write your own; it shows the same document as a page people can read.
---
spec: "1"
title: Morning assistant
version: "1.0.0"
---
# Morning assistant
Prepare a useful daily brief.
MUST[status]: keep tentative appointments tentative.
BECAUSE: an invitation is not a commitment.
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::
:::skill{id=prioritize title="Prioritize the day"}
Choose one useful, achievable focus task.
1. Review commitments and available focus time.
2. Choose one useful, achievable task.
3. Explain why it is a good first priority.
:::
Use :skill[Prioritize the day]{ref=#prioritize}.
:::workflow{id=brief dialect="instruction/workflow"}
name: morning-brief
steps:
start:
kind: manual
read:
kind: mcp.tool
depends_on:
- start
server: calendar
tool: events.list
timeout: 30s
retry:
max: 2
backoff: 2s
draft:
kind: agent
depends_on:
- read
instruction: Prepare a daily brief. Keep tentative appointments tentative.
review:
kind: human
depends_on:
- draft
question: Accept this daily brief?
schema:
type: string
enum:
- accept
- revise
timeout: 2h
route:
kind: switch
depends_on:
- review
on: "{{ steps.review.output }}"
cases:
accept: accepted
revise: revision
accepted:
kind: finish
depends_on:
- route
output: "{{ steps.draft.output }}"
revision:
kind: finish
depends_on:
- route
status: cancelled
reason: The reviewer requested a revision.
:::
---
authors: [Alex]
history:
- summary: Preserve appointment status.
sources:
- { title: Team guidance, uri: ./team.md } Where next
- Workflows: processes with steps, decisions and approvals.
- Concepts: how instructions are versioned, shared and followed.
- The specification: every part of the language, exactly.