Cette page n’est pas encore traduite.

Rules and blocks

This page is for developers who write or generate instruction documents. It lists every rule keyword and every block kind of the first edition (instruction/1): how each is written, the attributes it takes, and the exact text an agent receives from it. The tables are read from the specification's registry and the samples are delivered by the language service when this page is built, so they match what instruction deliver and spec_deliver give you.

Rule keywords

A rule is a line that starts with a keyword and a colon. These are every keyword the reader knows, and the kind each one reads as:

KeywordReads asFlagRuleMeaning
MUST:mustyesA binding obligation within its scope.
MUST NOT:neveryesA binding prohibition.
NEVER:neveryesA binding prohibition.
ALWAYS:mustyesA binding obligation within its scope.
SHOULD:shouldyesA recommended default; a departure should be explained. With not=true, a recommended avoidance.
SHOULD NOT:shouldnot=trueyesA recommended default; a departure should be explained. With not=true, a recommended avoidance.
AVOID:shouldnot=trueyesA recommended default; a departure should be explained. With not=true, a recommended avoidance.
MAY:mayyesA permission in the guidance. It grants no host capability.
GUARDRAIL:guardrailyesAn explicit high-importance boundary, for review and for the agent.
NOTE:noteadvisoryContext or advice, with no rule strength.
INFO:noteadvisoryContext or advice, with no rule strength.
TIP:tipadvisoryContext or advice, with no rule strength.
IMPORTANT:importantadvisoryContext or advice, with no rule strength.
WARNING:warningadvisoryContext or advice, with no rule strength.
CAUTION:cautionadvisoryContext or advice, with no rule strength.

The block kinds always, avoid and info are aliases: always reads as must, avoid reads as should with not=true, info reads as note. Keywords are upper case and matched exactly; Must: or must: is ordinary text.

The operative rules are must, should, may, never and guardrail. The advisories (note, tip, important, warning, caution) carry context with no rule strength. A rule is guidance to the agent: nothing enforces it at run time, and styling a guardrail doesn't make it a control.

Writing a rule

The same rule can be written several ways. Each line below is a rule:

Markdown
MUST[greet]: greet the customer by name.

**SHOULD:** answer in the customer's language.

- NEVER: promise a delivery date.
- MAY: offer a discount code when a delivery is late.

NEVER (if the customer is under 18): ask for payment details.
BECAUSE: Acme does not take payments from minors.

> [!WARNING]
> The order system is read-only on Sundays.

:::must{id=refund-method if="the order was paid by card" because="the bank reverses card payments only"}
Refund to the original card.
:::

An agent receives each in its canonical form:

Delivered text
MUST: greet the customer by name.

SHOULD: answer in the customer's language.

NEVER: promise a delivery date.

MAY: offer a discount code when a delivery is late.

NEVER (if the customer is under 18): ask for payment details.
BECAUSE: Acme does not take payments from minors.

### warning: warning

The order system is read-only on Sundays.

MUST (if the order was paid by card): Refund to the original card.
BECAUSE: the bank reverses card payments only
  • A line. KEYWORD: text, at the start of a paragraph, with at least one space after the colon. The text runs on until a blank line or a line that starts something else.
  • Emphasized. **MUST:** text, with matched ** markers. An unmatched marker makes no rule.
  • A list item or a quoted line. - NEVER: text or > MUST: text. Each item is its own rule, and the list marker isn't delivered.
  • An alert. A blockquote that starts with > [!KEYWORD] on its own line, case-insensitive, multiword keywords included (> [!MUST NOT]). An alert type that isn't a keyword stays an ordinary blockquote.
  • A container. :::must{if="…" because="…"} … :::, for a rule whose body has several paragraphs or blocks.

A keyword line interrupts the rule before it, so consecutive rule lines are separate rules without blank lines between them. A line that is not a keyword continues the rule above it. A keyword in the middle of a sentence, in a heading, in a table cell, in code or inside an example is not a rule.

Rule ids

MUST[confirm]: text names a rule confirm. The id grammar is letters, digits, ., _ and -, starting with a letter or digit. A rule id shares the document's id namespace with every block id and heading {#id}, and a repeated one is duplicate-id. An id is how an extending document targets an inherited rule (Includes, inheritance and extensions).

Conditions

NEVER (if the customer is under 18): text gives a rule a condition. There is exactly one space before (if, and the condition is one line of text without parentheses. In a container, write if="…".

The condition is delivered with the rule and interpreted by the agent. The resolver never evaluates it, so every rule reaches the agent whatever its condition. An empty condition, or a condition on an advisory (NOTE (if …):), is an invalid-attributes error.

Reasons

A BECAUSE: line right after a rule, in the same block, is that rule's reason. Blank lines and comments may come between them. because="…" on a container is the same. The reason is delivered on the line after its rule.

Two reasons for one rule are an error:

refunds.md
MUST: refund to the original payment method.
BECAUSE: the bank reverses card payments only.
BECAUSE: it is the law.
instruction validate refunds.md
INVALID  refunds.md
         line 3: this rule already has a reason: give it one BECAUSE  [reason-repeated]

A reason with no rule before it stays prose, with a warning:

refunds.md
Refunds take three to five working days.

BECAUSE: the bank needs that long.
instruction validate refunds.md
ok       refunds.md
         warning line 3: BECAUSE: follows no rule here, so it stays prose: put it right after the rule it explains  [orphan-reason]

A BECAUSE: line right after an advisory keyword line (NOTE:, TIP: and the others) is kept as that advisory's because attribute, with no warning, and is delivered on its Attributes: line rather than as a reason.

Directives

Every other block is a directive, written at the start of a line:

  • A container, :::kind{attributes}, its body on the following lines and a closing line of colons. The opener and the closing line hold nothing else.
  • A leaf, ::kind{attributes} on one line, for a block its attributes describe completely.
  • An inline object, :kind[label]{attributes} in prose. Those are on Inline references, links and annotations.

A container inside another uses fewer colons than its parent: ::::columns holds :::column. A container opened with as many colons as its parent, or closed with fewer than it opened with, is invalid-nesting. A container with no closing line is unclosed-directive: the end of the file doesn't close it.

A directive is recognized only at physical column zero, outside code, comments and HTML blocks. An indented one, or one in a list item or a blockquote, is ordinary text. A directive interrupts a paragraph and ends the list or quote around it.

:::kind words (words where the attribute list goes) is ordinary text. A well-formed directive of a kind this edition doesn't define is an unknown-kind error; it is kept as written and its body isn't read. A kind with an extension prefix, such as charts:metric, needs the alias charts in the front matter's extensions (Front matter), or it is extension-unavailable.

Attributes

An attribute list is one line between braces, right after the kind:

Markdown
:::context{id=hours title="Opening hours" class="wide,muted"}
We answer from 09:00 to 17:00, Monday to Friday.
:::

:::context{#holidays .wide .muted title="Holidays"}
Closed on public holidays in Germany.
:::

:::details{open title="Why these hours" x-reviewed-by=support-leads}
Most orders arrive during the working day.
:::
Delivered text
### Context: Opening hours

We answer from 09:00 to 17:00, Monday to Friday.

### Context: Holidays

Closed on public holidays in Germany.

### details: Why these hours

Attributes: {"x-reviewed-by":"support-leads"}

Most orders arrive during the working day.
  • Values. key=value (bare: no spaces, braces or quotes) or key="value" (a JSON string on one line). Keys are lower case.
  • Shorthands. {#hours} is id=hours, and each .wide adds to class. A repeated key, or a shorthand plus its key, is an error.
  • Flags. A key alone, such as open, is true. A boolean takes only true or false.
  • Types. An integer is -?[0-9]+, a number may have a decimal part, and a list is a comma-separated value whose members can't be empty. Free text keeps its commas.
  • Unknown keys. A key the kind doesn't take is invalid-attributes. A key starting x- is kept as an annotation with no effect, and is delivered.
  • Nothing runs. No attribute value is executable. Structured data goes in a YAML or JSON body, not in an attribute.

Every kind takes these common attributes, besides its own:

AttributeTypeMeaning
ididThe block's identity, unique in the document whatever its kind. `{#x}` is the same.
titlestring, one lineA display name, on one line. Generated headings in the delivered text use it.
classlistPresentation classes. `{.a .b}` adds to it. Never delivered.
formatone of markdown | yaml | json | csv | text | html | codeThe body's format, where the kind takes more than one.
verbatimbooleanKeeps a Markdown body literal: no rules, references or parameters are read in it.
srcstringWhere the object or resource is: a relative or absolute URI.
refstringA reference target: a URI, a local #id, an included #alias/id or a named reference.
modeone of live | pinnedlive (the default) reads the target when resolving; pinned needs sha256.
versionstringA version label of the target. A label, never a pin.
sha256sha256:<64 hex>The digest a pinned reference must match.
requiredbooleanA missing target is an error instead of a partial result.
descriptionstringA short description of the object.
stylestringA presentation token, never inline CSS. Never delivered.

In the delivered text, a block's id, title, class and style are left off its attribute line, and its title becomes its heading; a layout block also leaves off class, style, count, columns, span, open. A rule has no heading: it leaves off id, class and style, its if, because and not are in its label and reason, and a title on a rule stays on its attribute line. Every other attribute is delivered as one Attributes: line of canonical JSON (RFC 8785).

How a block is delivered

Each block becomes one unit of the delivered text, separated from the next by one blank line:

  • A rule is its label, its condition, its text, its reason on the next line, and its attribute line, if it has one, after that.
  • A policy, instruction or context is a ### Policy: Title heading (Instruction:, Context:), its attribute line, then its children.
  • An example is ### Example: Title (### Counterexample: with avoid=true), then its body fenced as markdown, so a rule-looking line in it can't read as a rule.
  • Any other Markdown-bodied kind is ### kind: Title, its attribute line, then every child. An advisory written as a keyword or an alert has no title, so its heading is ### note: note.
  • A structured kind is its heading, its attribute line, then its body fenced with its format.
  • An allowance is stated in one fixed sentence before its body (Allowances and wallets).

A heading's title is the block's title, else its id, else its kind. Layout never hides content: every tab, column, step and closed detail is delivered, in source order. The whole profile, with the resolved references and composition changes that follow the body, is on What an agent receives.

Every kind follows, family by family. Each row's example is checked and delivered when this page is built. spec_validate and instructions_validate list the capabilities a document needs as requires: the family of every kind it uses, plus agents for an agent with no protocol, src or endpoint (one the host runs) and spending for an allowance.

Guidance

Rules, and the blocks that group or name guidance. Each rule kind is written as a keyword, an alert or a container (above). A policy keeps each rule inside it a separate rule with its origin.

KindWritten asBodyIts own attributesWhat it is
always
alias of must
:::always, keyword, alertMarkdownif: string, because: stringAn alias of must.
Example and what the agent receives
Code
ALWAYS: sign replies with the team's name.

Delivered:

Code
MUST: sign replies with the team's name.
avoid
alias of should
:::avoid, keyword, alertMarkdownif: string, because: stringAn alias of should with not=true.
Example and what the agent receives
Code
AVOID: technical terms the customer did not use.

Delivered:

Code
SHOULD NOT: technical terms the customer did not use.
context:::contextMarkdownnoneLabelled reference material: what the agent should know, not what it must do.
Example and what the agent receives
Code
:::context{title="Where orders live"}
Orders are in the order system. Returns are in the warehouse system.
:::

Delivered:

Code
### Context: Where orders live

Orders are in the order system. Returns are in the warehouse system.
guardrail:::guardrail, keyword, alertMarkdownif: string, because: stringAn explicit high-importance boundary. Styling it enforces nothing.
Example and what the agent receives
Code
GUARDRAIL: stop and ask a person before any refund over 500 EUR.

Delivered:

Code
GUARDRAIL: stop and ask a person before any refund over 500 EUR.
instruction:::instructionMarkdownnoneA named, reusable block of guidance.
Example and what the agent receives
Code
:::instruction{id=tone title="Tone"}
Write short, friendly sentences.
:::

Delivered:

Code
### Instruction: Tone

Write short, friendly sentences.
may:::may, keyword, alertMarkdownif: string, because: stringA permission in the guidance. It grants no host capability.
Example and what the agent receives
Code
MAY: offer a discount code when a delivery is late.

Delivered:

Code
MAY: offer a discount code when a delivery is late.
must:::must, keyword, alertMarkdownif: string, because: stringA binding obligation. MUST and ALWAYS read as it.
Example and what the agent receives
Code
MUST: confirm the order number before you change an order.

Delivered:

Code
MUST: confirm the order number before you change an order.
never:::never, keyword, alertMarkdownif: string, because: stringA binding prohibition. MUST NOT and NEVER read as it.
Example and what the agent receives
Code
NEVER: share another customer's details.

Delivered:

Code
NEVER: share another customer's details.
policy:::policyMarkdownscope: string, authority: string, source: stringGroups related rules under a title, with an optional scope, authority and source. Each rule inside stays a rule.
Example and what the agent receives
Code
:::policy{id=refunds title="Refunds" scope="orders"}
MUST: refund to the original payment method.
:::

Delivered:

Code
### Policy: Refunds

Attributes: {"scope":"orders"}

MUST: refund to the original payment method.
should:::should, keyword, alertMarkdownif: string, because: string, not: booleanA recommended default; with not=true (SHOULD NOT), a recommended avoidance.
Example and what the agent receives
Code
SHOULD: answer in the customer's language.

Delivered:

Code
SHOULD: answer in the customer's language.

Advisories and examples

Labelled advice with no rule strength, and quoted examples. An example's body is base Markdown with nothing of the language read in it: no rules, references or parameters. Only its closing line is recognized. verbatim=true does the same for any Markdown-bodied block.

KindWritten asBodyIts own attributesWhat it is
caution:::caution, keyword, alertMarkdownnoneA caution, with no rule strength.
Example and what the agent receives
Code
CAUTION: a cancelled order can't be restored.

Delivered:

Code
### caution: caution

a cancelled order can't be restored.
example:::exampleMarkdown, quotedavoid: booleanQuoted material, labelled as an example; avoid=true makes it a counterexample. Its body is never read for rules, references or parameters.
Example and what the agent receives
Code
:::example{title="A good first line"}
MUST: this line is quoted, not a rule.
Hi Sam, your refund is on its way.
:::

Delivered:

Code
### Example: A good first line

```markdown
MUST: this line is quoted, not a rule.
Hi Sam, your refund is on its way.
```
important:::important, keyword, alertMarkdownnoneSomething important, with no rule strength.
Example and what the agent receives
Code
IMPORTANT: prices include VAT.

Delivered:

Code
### important: important

prices include VAT.
info
alias of note
:::info, keyword, alertMarkdownnoneAn alias of note.
Example and what the agent receives
Code
INFO: the warehouse is in Leipzig.

Delivered:

Code
### note: note

the warehouse is in Leipzig.
note:::note, keyword, alertMarkdownnoneA note. NOTE and INFO read as it.
Example and what the agent receives
Code
NOTE: refunds take three to five working days.

Delivered:

Code
### note: note

refunds take three to five working days.
tip:::tip, keyword, alertMarkdownnoneA tip.
Example and what the agent receives
Code
TIP: the order number is in the email's subject line.

Delivered:

Code
### tip: tip

the order number is in the email's subject line.
warning:::warning, keyword, alertMarkdownnoneA warning, with no rule strength.
Example and what the agent receives
Code
> [!WARNING]
> The order system is read-only on Sundays.

Delivered:

Code
### warning: warning

The order system is read-only on Sundays.

Contracts

What the agent answers with, the inputs it collects, its parameters and its terms. A value collected by a form becomes a parameter only through a declared parameter (Parameters).

KindWritten asBodyIts own attributesWhat it is
form:::formMarkdownnoneThe inputs to collect. A renderer may show fields; the body stays shared.
Example and what the agent receives
Code
:::form{title="Before you start"}
- The order number
- The email address on the order
:::

Delivered:

Code
### form: Before you start

- The order number
- The email address on the order
glossary:::glossaryMarkdownnoneTerms and their definitions, as a definition list. Terms create no ids.
Example and what the agent receives
Code
:::glossary
RMA
: A return authorization number.
:::

Delivered:

Code
### glossary: glossary

RMA
: A return authorization number.
output:::outputMarkdownresponse-format: string, schema: stringThe response contract: a response-format and an optional schema reference. A schema alone doesn't promise the host validates answers.
Example and what the agent receives
Code
:::output{response-format=markdown title="Every reply"}
What you did, what you did not do, and what happens next.
:::

Delivered:

Code
### output: Every reply

Attributes: {"response-format":"markdown"}

What you did, what you did not do, and what happens next.
param::paramnone (leaf)name (required): string, type: one of string | number | integer | boolean | enum | list | url | duration, values: list, default: any, example: any, source: one of input | workspace | identity | static, required: boolean, description: stringDeclares a parameter in the body (name required), as the front matter's parameters do.
Example and what the agent receives
Code
::param{name=region type=enum values="eu,us" default=eu description="Where the customer is"}

Delivered:

Code
### param: param

Attributes: {"default":"eu","description":"Where the customer is","name":"region","type":"enum","values":["eu","us"]}

Connected objects

People, roles, skills, MCP servers, tools, agents, services, sources and wallets the guidance refers to. Declaring one grants nothing: a server's tools, allow and deny say what the author intends, and the host decides what may be connected and called. Their targets, protocols and the integrations policy are on Tools, skills, agents and services.

KindWritten asBodyIts own attributesWhat it is
agent:::agent, ::agentMarkdownprotocol: string, endpoint: string, binding: string, tenant: string, skills: list, resolver: string, account: string
id required
Another agent: an A2A agent (protocol=a2a, with src or endpoint), or one the host runs.
Example and what the agent receives
Code
::agent{id=travel title="Travel researcher" protocol=a2a src="https://agents.example.com/.well-known/agent-card.json"}

Delivered:

Code
### agent: Travel researcher

Attributes: {"protocol":"a2a","src":"https://agents.example.com/.well-known/agent-card.json"}
mcp:::mcp, ::mcpMarkdownregistry: string, server: string, account: string, tools: list, allow: list, deny: list, resolver: string, protocol: string
id required
An MCP server: an endpoint, a registry entry or server metadata. tools, allow and deny state intended use and grant nothing.
Example and what the agent receives
Code
:::mcp{id=orders title="Orders" src="https://orders.example.com/mcp" tools="orders.get,orders.refund"}
Read orders freely. Ask before a refund.
:::

Delivered:

Code
### mcp: Orders

Attributes: {"src":"https://orders.example.com/mcp","tools":["orders.get","orders.refund"]}

Read orders freely. Ask before a refund.
person:::person, ::personMarkdownrole: string, resolver: string, account: string, protocol: string
id required
A person, by a stable id and a readable label.
Example and what the agent receives
Code
::person{id=sam title="Sam Lee" role=approver}

Delivered:

Code
### person: Sam Lee

Attributes: {"role":"approver"}
role:::role, ::roleMarkdownresolver: string, account: string, protocol: string
id required
A role, which may be a different person in each deployment.
Example and what the agent receives
Code
::role{id=on-call title="On-call engineer"}

Delivered:

Code
### role: On-call engineer
service:::service, ::serviceMarkdownresolver: string, account: string, media-type: string, protocol: string
id required
A service other than MCP, such as an OpenAPI description (protocol=openapi/3.1).
Example and what the agent receives
Code
::service{id=crm title="CRM" protocol=openapi/3.1 src="https://api.example.com/openapi.json"}

Delivered:

Code
### service: CRM

Attributes: {"protocol":"openapi/3.1","src":"https://api.example.com/openapi.json"}
skill:::skill, ::skillMarkdowntrigger: string, resolver: string, protocol: string
id required
An Agent Skills SKILL.md, local guidance or another instruction. Its trigger is guidance, not a condition the resolver checks.
Example and what the agent receives
Code
:::skill{id=triage src="./skills/triage/SKILL.md" trigger="a new ticket arrives"}
Use it to sort tickets by urgency.
:::

Delivered:

Code
### skill: triage

Attributes: {"src":"./skills/triage/SKILL.md","trigger":"a new ticket arrives"}

Use it to sort tickets by urgency.
source:::source, ::sourceMarkdownresolver: string, account: string, media-type: string, protocol: string
id required
A source of information the guidance draws on.
Example and what the agent receives
Code
::source{id=handbook title="Support handbook" src="https://example.com/handbook"}

Delivered:

Code
### source: Support handbook

Attributes: {"src":"https://example.com/handbook"}
tool:::tool, ::toolMarkdownserver (required): string, name (required): string, allow: list, deny: list, protocol: string
id required
One tool of a server: server=#id names the document's mcp or service, and name the tool.
Example and what the agent receives
Code
::mcp{id=orders title="Orders" src="https://orders.example.com/mcp"}

::tool{id=refund server=#orders name=orders.refund}

Delivered:

Code
### mcp: Orders

Attributes: {"src":"https://orders.example.com/mcp"}

### tool: refund

Attributes: {"name":"orders.refund","server":"#orders"}
wallet:::wallet, ::walletMarkdownaccount: string, rails: list, resolver: string, protocol: string
id required
A payment instrument the host holds, by its account alias, and the rails it may be used on. It carries no card, key or token.
Example and what the agent receives
Code
::wallet{id=team-card title="Team card" account=team rails="x402"}

Delivered:

Code
### wallet: Team card

Attributes: {"account":"team","rails":["x402"]}

Authority

What an agent may spend, on what, and who approves. An allowance only narrows what the host allows, and a host applies it only when it is granted spending. See Allowances and wallets.

KindWritten asBodyIts own attributesWhat it is
allowance:::allowanceMarkdownwallet: list, currency: string, max: string, budget: string, per: string, times: string, payees: string, categories: list, from: string, until: string, approve-above: string, approver: string
id required
What an agent may spend, on what, and who approves.
Example and what the agent receives
Code
:::allowance{id=travel title="Travel" wallet=team-card currency=EUR budget=200 per=month approve-above=50 approver=sam}
Train tickets for customer visits only.
:::

Delivered:

Code
### allowance: Travel

Allowance "Travel" (#travel): pay from team-card in EUR; 200 per calendar month (UTC); ask sam before any payment above 50.

Train tickets for customer visits only.

Resources, media and drawings

Images, audio, video, PDFs, figures, diagrams and drawings. The Markdown body is the shared description. The specification asks an informative media block for alt text, a description or a transcript, and a decorative image for decorative=true; the reader doesn't check it. A PDF takes page (1 or more); audio and video take start and end in milliseconds, with end after start; an image takes region as x,y,width,height, fractions inside the unit square. A selector isn't a promise to extract text.

KindWritten asBodyIts own attributesWhat it is
audio:::audio, ::audioMarkdownmedia-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: stringAudio, optionally a range in milliseconds (start, end).
Example and what the agent receives
Code
:::audio{id=call src="./call.mp3" start=0 end=30000 transcript="./call.txt"}
The first 30 seconds of a good support call.
:::

Delivered:

Code
### audio: call

Attributes: {"end":30000,"src":"./call.mp3","start":0,"transcript":"./call.txt"}

The first 30 seconds of a good support call.
diagram:::diagram, ::diagramMarkdownmedia-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: stringA diagram: a description, usually around a mermaid fence. A diagram is never an executable workflow.
Example and what the agent receives
Code
::::diagram{id=states title="Order states"}
```mermaid
stateDiagram-v2
  Paid --> Shipped
  Shipped --> Delivered
```
::::

Delivered:

Code
### diagram: Order states

```mermaid
stateDiagram-v2
  Paid --> Shipped
  Shipped --> Delivered
```
drawing:::drawing, ::drawingMarkdownmedia-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: stringAn editable drawing: its source (SVG, Excalidraw, JSON Canvas), an optional preview and a description.
Example and what the agent receives
Code
::drawing{id=layout src="./reply.excalidraw" preview="./reply.svg" alt="A reply: greeting, answer, next step"}

Delivered:

Code
### drawing: layout

Attributes: {"alt":"A reply: greeting, answer, next step","preview":"./reply.svg","src":"./reply.excalidraw"}
figure:::figureMarkdownmedia-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: stringA figure: shared content with a caption.
Example and what the agent receives
Code
:::figure{id=weekly caption="Refunds per week"}
![Refunds per week, rising in December](./refunds.png)
:::

Delivered:

Code
### figure: weekly

Attributes: {"caption":"Refunds per week"}

![Refunds per week, rising in December](./refunds.png)
image:::image, ::imageMarkdownmedia-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: stringAn image. An informative one has alt text or a description; a decorative one says decorative=true.
Example and what the agent receives
Code
::image{id=flow src="./refund-flow.png" alt="The refund flow: request, check, approve, pay"}

Delivered:

Code
### image: flow

Attributes: {"alt":"The refund flow: request, check, approve, pay","src":"./refund-flow.png"}
pdf:::pdf, ::pdfMarkdownmedia-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: stringA PDF, optionally one page.
Example and what the agent receives
Code
::pdf{id=policy title="Refund policy" src="./refund-policy.pdf" page=2}

Delivered:

Code
### pdf: Refund policy

Attributes: {"page":2,"src":"./refund-policy.pdf"}
resource:::resource, ::resourceMarkdownmedia-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: stringAny resource, by its address and media type.
Example and what the agent receives
Code
:::resource{id=prices title="Price list" src="./prices.csv" media-type=text/csv}
The current price of every plan.
:::

Delivered:

Code
### resource: Price list

Attributes: {"media-type":"text/csv","src":"./prices.csv"}

The current price of every plan.
video:::video, ::videoMarkdownmedia-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: stringVideo, optionally a range in milliseconds (start, end).
Example and what the agent receives
Code
:::video{id=walkthrough src="./refunds.mp4" start=1000 end=12000}
How a refund is approved in the order system.
:::

Delivered:

Code
### video: walkthrough

Attributes: {"end":12000,"src":"./refunds.mp4","start":1000}

How a refund is approved in the order system.

Technical objects

Code, data, configuration, schedules, workflows, sandboxes, tests and evaluations. Structured bodies are YAML unless format says otherwise, follow the YAML rules on Front matter, notes and comments, and are delivered as fenced source. A body that doesn't parse, or isn't a mapping where one is needed, is invalid-structured-body. Nothing runs, arms or deploys when a document is read, rendered or delivered. The native workflow language is on Workflow node reference, and eval cases on Evals and tests.

KindWritten asBodyIts own attributesWhat it is
config:::configYAML, JSON (default YAML)dialect (required): string, adapter: string, target: string, schema: string, schema-sha256: sha256:<64 hex>
id required
Runtime configuration for an explicit compiler or export (dialect required), never extra guidance.
Example and what the agent receives
Code
:::config{id=runtime dialect="agentd/config" adapter=agentd}
agent:
  name: support-agent
:::

Delivered:

Code
### config: runtime

Attributes: {"adapter":"agentd","dialect":"agentd/config"}

```yaml
agent:
  name: support-agent
```
data:::dataYAML, JSON, CSV, TEXT (default YAML)schema: string
id required
Data: YAML (the default), JSON, CSV or text. CSV cells stay strings and are never evaluated.
Example and what the agent receives
Code
:::data{id=regions format=csv}
region,currency
eu,EUR
us,USD
:::

Delivered:

Code
### data: regions

Attributes: {"format":"csv"}

```csv
region,currency
eu,EUR
us,USD
```
eval:::evalYAML, JSON (default YAML)dialect: string, adapter: string, target: string, schema: string, schema-sha256: sha256:<64 hex>
id required
Model cases: each a name, a message and what the answer is expected to hold. instruction eval runs those with no adapter or adapter=instruction.md/claude.
Example and what the agent receives
Code
:::eval{id=greeting}
cases:
  - name: greets by name
    message: "Hi, I'm Sam. Where is my order?"
    expect: { contains: ["Sam"] }
:::

Delivered:

Code
### eval: greeting

```yaml
cases:
  - name: greets by name
    message: "Hi, I'm Sam. Where is my order?"
    expect: { contains: ["Sam"] }
```
properties:::propertiesYAML, JSON (default YAML)patch: booleanA structured mapping attached to its parent block. A key may not repeat one of the parent's attributes, and a parent has one at most.
Example and what the agent receives
Code
::::context{id=hours title="Opening hours"}
We answer from 09:00 to 17:00.

:::properties
timezone: Europe/Berlin
:::
::::

Delivered:

Code
### Context: Opening hours

We answer from 09:00 to 17:00.

### properties: properties

```yaml
timezone: Europe/Berlin
```
sandbox:::sandboxYAML, JSON (default YAML)dialect: string, adapter: string, target: string, schema: string, schema-sha256: sha256:<64 hex>
id required
An execution profile for an explicit test or export adapter: data, not a runtime.
Example and what the agent receives
Code
:::sandbox{id=python dialect="oci"}
image: python:3.12-slim
network: none
:::

Delivered:

Code
### sandbox: python

Attributes: {"dialect":"oci"}

```yaml
image: python:3.12-slim
network: none
```
schedule:::scheduleYAML, JSON (default YAML)dialect (required): string, adapter: string, target: string, schema: string, schema-sha256: sha256:<64 hex>
id required
A schedule in a named dialect. Reading or rendering it arms nothing.
Example and what the agent receives
Code
:::schedule{id=weekdays dialect="cron"}
at: "0 9 * * 1-5"
:::

Delivered:

Code
### schedule: weekdays

Attributes: {"dialect":"cron"}

```yaml
at: "0 9 * * 1-5"
```
script:::scriptMarkdownlang: string, sandbox: string, entry: string
id required
Code with its documentation (lang, sandbox, entry). It never runs by being read.
Example and what the agent receives
Code
::::script{id=total lang=python entry=total}
Adds up an order's lines.

```python
def total(lines):
    return sum(line["price"] for line in lines)
```
::::

Delivered:

Code
### script: total

Attributes: {"entry":"total","lang":"python"}

Adds up an order's lines.

```python
def total(lines):
    return sum(line["price"] for line in lines)
```
test:::testYAML, JSON (default YAML)dialect: string, adapter: string, target: string, schema: string, schema-sha256: sha256:<64 hex>
id required
Fixtures and assertions for code or workflows, for a test adapter.
Example and what the agent receives
Code
:::test{id=total-cases target=#total}
cases:
  - name: two lines
    input: [{ price: 2 }, { price: 3 }]
    expect: 5
:::

Delivered:

Code
### test: total-cases

Attributes: {"target":"#total"}

```yaml
cases:
  - name: two lines
    input: [{ price: 2 }, { price: 3 }]
    expect: 5
```
workflow:::workflowYAML, JSON (default YAML)dialect (required): string, adapter: string, target: string, schema: string, schema-sha256: sha256:<64 hex>
id required
A workflow in a named dialect. instruction/workflow is the native one, checked against its node registry.
Example and what the agent receives
Code
:::workflow{id=triage dialect="instruction/workflow"}
name: triage
steps:
  start:
    kind: manual
  sort:
    kind: agent
    depends_on: [start]
    instruction: Sort the new tickets by urgency.
  done:
    kind: finish
    depends_on: [sort]
    output: "{{ steps.sort.output }}"
:::

Delivered:

Code
### workflow: triage

Attributes: {"dialect":"instruction/workflow"}

```yaml
name: triage
steps:
  start:
    kind: manual
  sort:
    kind: agent
    depends_on: [start]
    instruction: Sort the new tickets by urgency.
  done:
    kind: finish
    depends_on: [sort]
    output: "{{ steps.sort.output }}"
```

Layout

Sections, columns, grids, cards, tabs, steps, details and asides. A layout has no instruction authority. A column belongs in columns, a tab in tabs and a step in steps; anywhere else is invalid-nesting.

KindWritten asBodyIts own attributesWhat it is
aside:::asideMarkdownnoneContent beside the main text.
Example and what the agent receives
Code
:::aside{title="Background"}
The refund rules changed in 2025.
:::

Delivered:

Code
### aside: Background

The refund rules changed in 2025.
card:::cardMarkdownnoneA card, in a grid or on its own.

Shown with grid.

column
inside columns
:::columnMarkdownspan: integer 1–12One column, inside columns (span 1–12).

Shown with columns.

columns:::columnsMarkdowncount: integer 1–12Columns (count 1–12). A renderer may stack them; reading order stays.
Example and what the agent receives
Code
::::columns{count=2}
:::column
MUST: say what you changed.
:::
:::column
NEVER: change an order without asking.
:::
::::

Delivered:

Code
### columns: columns

### column: column

MUST: say what you changed.

### column: column

NEVER: change an order without asking.
details:::detailsMarkdownopen: booleanA disclosure (open=true shows it open). Closed or not, it is delivered.
Example and what the agent receives
Code
:::details{title="Why 30 days"}
It matches the law in most of the countries we ship to.
:::

Delivered:

Code
### details: Why 30 days

It matches the law in most of the countries we ship to.
grid:::gridMarkdowncolumns: integer 1–12A grid (columns 1–12) of cards.
Example and what the agent receives
Code
::::grid{columns=2}
:::card{title="Email"}
Answer within one working day.
:::
:::card{title="Chat"}
Answer within five minutes.
:::
::::

Delivered:

Code
### grid: grid

### card: Email

Answer within one working day.

### card: Chat

Answer within five minutes.
section:::sectionMarkdownnoneA titled section of content.
Example and what the agent receives
Code
:::section{id=returns title="Returns"}
A return is accepted within 30 days.
:::

Delivered:

Code
### section: Returns

A return is accepted within 30 days.
step
inside steps
:::stepMarkdownnoneOne step, inside steps.

Shown with steps.

steps:::stepsMarkdownnoneNumbered steps.
Example and what the agent receives
Code
::::steps{title="Refund"}
:::step{title="Check"}
Find the order and its payment.
:::
:::step{title="Refund"}
Refund to the original payment method.
:::
::::

Delivered:

Code
### steps: Refund

### step: Check

Find the order and its payment.

### step: Refund

Refund to the original payment method.
tab
inside tabs
:::tabMarkdownnoneOne tab, inside tabs.

Shown with tabs.

tabs:::tabsMarkdownnoneTabs. A fenced code block directly inside tabs is a tab of its own. Every tab is delivered.
Example and what the agent receives
Code
::::tabs{title="Greeting"}
:::tab{title="English"}
Hello, and thank you for writing.
:::
:::tab{title="German"}
Hallo, und danke für Ihre Nachricht.
:::
::::

Delivered:

Code
### tabs: Greeting

### tab: English

Hello, and thank you for writing.

### tab: German

Hallo, und danke für Ihre Nachricht.

Presentation

A named component a renderer may draw. Its Markdown body is the fallback, shown where the component isn't installed, and is all the agent receives. A component adds no guidance beyond it.

KindWritten asBodyIts own attributesWhat it is
component:::componentMarkdowncomponent (required): string, stylesheet: stringAn installed component a renderer may draw, optionally with a stylesheet. Unknown components show the fallback.
Example and what the agent receives
Code
:::component{component="plan-table"}
Community is free. Pro and Team are billed per month.
:::

Delivered:

Code
### component: component

Attributes: {"component":"plan-table"}

Community is free. Pro and Team are billed per month.

Composition

Including other documents and patching inherited ones. The examples below are resolved over a shared fragment and a base document; their full contract is on Includes, inheritance and extensions.

KindWritten asBodyIts own attributesWhat it is
embed:::embed, ::embedMarkdownmedia-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: string
src required
Shows a resource or a fragment in place, without importing its definitions.
Example and what the agent receives
Code
::embed{src="./brief.pdf" page=2 title="Example brief"}

Delivered:

Code
### embed: Example brief

Attributes: {"page":2,"src":"./brief.pdf"}
extend:::extendMarkdowntarget (required): string, reason: string, position: one of prepend | appendAdds children before or after an inherited block's (position=append by default).
Example and what the agent receives
Code
:::extend{target="#base/tone" position=append}
SHOULD: use the customer's first name.
:::

Delivered:

Code
# Base

### Instruction: Tone

Write short, friendly sentences.

SHOULD: use the customer's first name.

### Instruction: Discounts

MAY: offer 10% off a late order.

### Composition changes

- extend base/tone (origin: document.md)
include::includenone (leaf)as (required): id
src required
Inserts another document's body or a selected part of it, under an alias (as).
Example and what the agent receives
Code
::include{src="./shared.md#id=privacy" as=shared}

Delivered:

Code
### Policy: Privacy

NEVER: repeat a customer's address back to them.
remove::removenone (leaf)target (required): string, reason: stringRemoves an inherited block.
Example and what the agent receives
Code
::remove{target="#base/discounts" reason="This team gives no discounts."}

Delivered:

Code
# Base

### Instruction: Tone

Write short, friendly sentences.

### Composition changes

- remove base/discounts (origin: document.md) — This team gives no discounts.
replace:::replaceMarkdown, YAML, JSON (default Markdown)target (required): string, reason: stringReplaces an inherited block by its qualified id.
Example and what the agent receives
Code
:::replace{target="#base/tone" reason="Shorter for chat"}
Write one or two sentences.
:::

Delivered:

Code
# Base

### Instruction: Tone

Write one or two sentences.

### Instruction: Discounts

MAY: offer 10% off a late order.

### Composition changes

- replace base/tone (origin: document.md) — Shorter for chat

Code fences

An ordinary fenced code block keeps its language and its text exactly. Nothing in it is read as the language: no rules, directives, references or parameters. A trailing attribute list on the info line takes id, title, filename, highlight (lines such as 2-3,5), caption and preview; the language is the first word.

Markdown
```python {#format filename="format.py" highlight="2" caption="Keep the status visible"}
def line(event):
    return f"{event['time']}: {event['title']} ({event['status']})"
```

```html {title="Reminder email"}
<p>Your 09:00 meeting is <b>tentative</b>.</p>
```

```svg {caption="Two steps"}
<svg viewBox="0 0 120 40"><rect x="2" y="2" width="50" height="36" fill="none" stroke="currentColor"/><rect x="68" y="2" width="50" height="36" fill="none" stroke="currentColor"/></svg>
```

The agent receives every fence unchanged, attribute list included:

Delivered text
```python {#format filename="format.py" highlight="2" caption="Keep the status visible"}
def line(event):
    return f"{event['time']}: {event['title']} ({event['status']})"
```

```html {title="Reminder email"}
<p>Your 09:00 meeting is <b>tentative</b>.</p>
```

```svg {caption="Two steps"}
<svg viewBox="0 0 120 40"><rect x="2" y="2" width="50" height="36" fill="none" stroke="currentColor"/><rect x="68" y="2" width="50" height="36" fill="none" stroke="currentColor"/></svg>
```

What a reader of the rendered document sees depends on the language:

Language Drawn as
html Two tabs: Rendered, the page the code describes, and Code. The page is drawn in a sandboxed frame that runs no script, submits no form, can't reach the host page or its storage, and loads only images and styles. preview=false keeps the fence as code only.
mermaid A diagram, drawn when the Mermaid runtime loads. Its source shows until then.
svg A drawing, reduced to shapes, paths and text (no scripts, links, styles, images or event handlers). A fence that isn't an SVG stays code.
math A display formula, as its source.
instruction Code. In someone else's Markdown, the renderer's script draws an instruction, instruction-md or instruction.md fence as an instruction (Embed).
Any other Code.

A diagram is a description, never a workflow: a Mermaid flowchart doesn't run. Inside tabs, a fence that isn't in a tab is a tab of its own, titled by its title, else its filename, else its language:

Markdown
:::tabs{title="Install"}
```bash {title="npm"}
npm i -g instruction.md
```
```bash {title="pnpm"}
pnpm add -g instruction.md
```
:::
Delivered text
### tabs: Install

```bash {title="npm"}
npm i -g instruction.md
```
```bash {title="pnpm"}
pnpm add -g instruction.md
```

If a block doesn't read

What you see Why What to do
:::kind is not closed: end it with a line of ::: (unclosed-directive) A container has no closing line. Add a line of as many colons as the opener.
… opens inside a ::: container with as many colons or more (invalid-nesting) An inner container uses as many colons as its parent. Give the outer one more colons: ::::columns around :::column.
:::column belongs inside :::columns (invalid-nesting) A column, tab or step outside its parent. Put it inside columns, tabs or steps.
"key" is not an attribute this kind takes (invalid-attributes) A key the kind and the common attributes don't have. Check the kind's row above, or write it as x-key.
::kind needs id=… (invalid-attributes) A required attribute is missing. Add it. Each kind's required attributes are in its row above.
the id "…" is used twice (duplicate-id) Two blocks, rules or headings share an id. Rename one: ids are unique across the document, whatever their kind.
NOTE is advice, not a rule: it takes no (if …) condition (invalid-attributes) A condition on an advisory. Make it a rule, or write the condition in its text.
:::kind is not a kind of this specification (unknown-kind) A misspelled kind, or one from Specification 1.1. Use a kind from the tables above; Upgrade from Specification 1.1 converts old blocks.
A rule arrives as plain prose The keyword is lower case, indented four spaces, in a heading or table cell, or has no space after its colon. Start the line with the upper-case keyword, a colon and a space.

Every code, with the fix the language service offers, is on Diagnostics and fixes. Still stuck? Ask support.

Last checked against the product:

Was this page helpful? Report a problem