Language reference

This reference is for developers who write, generate or check instruction documents. It describes the first edition of the language, instruction/1, as instruction.md's reader implements it: every keyword, block, attribute and key, and the exact text a model receives. The normative text is the specification.

A minimal document

An instruction is a UTF-8 Markdown file. This one is complete and valid:

support-replies.md
---
spec: "1"
---

# Support replies

You answer Acme's customers by email.

MUST: greet the customer by name.
  • Front matter. The --- lines at the top hold YAML. spec: "1" names the edition. Front matter is optional: without it, the document is read as edition 1.
  • Body. Everything else is Markdown, shared by the people who read it and the agent that follows it. A heading and a sentence are ordinary Markdown.
  • A rule. A line that starts with a rule keyword and a colon, here MUST:, is a rule. The others are listed on Rules and blocks.

Check it and read what a model receives, offline, with the CLI (npm i -g instruction.md):

Shell
instruction validate support-replies.md
instruction deliver support-replies.md
Output
ok       support-replies.md
# Support replies

You answer Acme's customers by email.

MUST: greet the customer by name.

instruction validate exits 1 when a document has an error, and prints warnings without failing (--strict fails on them too). instruction deliver prints the delivered text, reading the bases and includes it names from files beside it. For a document that names none, it is the same text spec_deliver returns. For a released version, instructions_versions_read with resolve: true returns it; an instruction:// resource serves the source as written, not this text.

The parts of a document

A document has up to four regions. Only the body reaches the agent.

Only the body reaches the agent. Front matter, comments and backmatter are never delivered.
Region Where Delivered Page
Front matter From the first line, between two lines of exactly --- Never Front matter, notes and comments
Body Everything between the front matter and the backmatter Yes, in the delivered text Rules and blocks
Comments <!-- … --> anywhere in the body, outside code Never Comments
Backmatter After a blank line and a plain ---, when the next line that isn't blank or a YAML comment starts with a known key such as owners: Never Backmatter

Here is a document with all four, and the text an agent receives from it:

support-replies.md
---
spec: "1"
title: Support replies
language: en
---

# Support replies

<!-- Reviewed with the support leads in November. -->
You answer Acme's customers by email.

MUST: greet the customer by name.

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

---
owners: [support-leads]
review: { next: "2027-05-01" }
Delivered text
# Support replies

You answer Acme's customers by email.

MUST: greet the customer by name.

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

The front matter, the comment and the backmatter are gone. The rule, its condition and its reason are delivered in their canonical form. The full text profile is on What an agent receives.

What the language has

The first edition defines 65 block kinds, 15 keywords (rule words and advisories) and 19 inline kinds, all listed in its registry (registry.json). These pages describe them topic by topic.

Tools that read the language

The same reader is behind every tool, so they agree on what a document means.

Where Check See what a model receives Other
The CLI (instruction) instruction validate <file...> [--json] [--strict] [--quiet] instruction deliver <file> [name=value ...] [--resolved] instruction fmt, instruction tree, instruction digest, instruction render --view delivered
The MCP server spec_validate (any text), instructions_validate (a stored draft) spec_deliver (any text), instructions_versions_read with resolve: true (a released version) spec_format, spec_outline, spec_fixes, spec_explain, the spec://kinds resources
The editor The Problems list, as you type Quick fixes
VS Code Diagnostics as you type Quick fixes (VS Code)

A release runs the same check as spec_validate and instructions_validate: a draft with an error can't be released, and warnings don't stop it. instruction validate runs it too, except for one check that only the server makes: a source that holds the host's host-integrations lines (The host's lines). The CLI's commands are on CLI commands, the tools on Tool reference and every diagnostic on Diagnostics and fixes.

The specification

The specification is the normative text. These pages follow it and say where instruction.md's reader adds to it. The sections these pages cover:

Topic Specification Reference page
Front matter, backmatter, YAML, comments §3 Front matter, notes and comments
Directives, attributes, identities §5 Rules and blocks
Rules, policies, examples §6 Rules and blocks
The block registry, layout, media, code §7, §8, §9 Rules and blocks
People, skills, MCP, agents, allowances §10 Tools, skills, agents and services, Allowances and wallets
References §11 Inline references, links and annotations
Parameters §12 Parameters
Composition §13, §15 Includes, inheritance and extensions
Resolution and the delivered text §14 What an agent receives
Diagnostics §18 Diagnostics and fixes

The specification's Markdown source is at /specification/1/specification.md, and the conformance vectors that pin the delivered text are in its repository.

Editions

A document names its edition with spec in its front matter. This reader knows one, "1"; the integer 1 reads as "1", and a document without spec is read as "1". Any other value is an unsupported-format error, so a document written for a later edition is refused rather than misread.

instruction.md reads only the first edition. A line still written in Specification 1.1, such as a :::when variant or a ::!kind block, is an error (instruction.md/legacy-syntax) with a fix that converts the document. See Upgrade from Specification 1.1.

Last checked against the product:

Was this page helpful? Report a problem