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.

morning-assistant.md
---
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.

WordWhat it meansFor example
MUSTA requirementask Alex before changing an invitation.
SHOULDA considered defaultkeep the daily brief under 150 words.
MAYAn allowed choicesuggest a focus task when time is available.
NEVERA prohibitionreveal a private event to another person.
SHOULD NOTA discouraged actionplan around it as a confirmed commitment.
A rule and its reason
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:

A rule with a condition
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.

A policy
:::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.
:::
A guardrail
:::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.

Guidance, an example and the expected output
:::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).

A tool connection
:::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.

A skill and a reference to it
:::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.

A person, and a rule that names 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.

morning-assistant.md
---
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.