Front matter, notes and comments
This page is for developers who write or generate instruction documents. It covers the parts of a document that are about the document rather than for the agent: the front matter at the top, the backmatter at the end, and comments anywhere. None of them is ever delivered to a model. Every key below is read from the reader's own lists (FRONT_MATTER_KEYS and BACKMATTER_KEYS), and every sample is checked and delivered when this page is built.
Front matter
Front matter is optional YAML at the top of the document:
---
spec: "1"
id: https://acme.example/instructions/support-replies
title: Support replies
description: How Acme's support agent answers customers by email.
version: "2026-11"
language: en
tags: [support, email]
license: CC-BY-4.0
parameters:
region: { type: enum, values: [eu, us], default: eu }
---
# Support replies
You answer Acme's customers in the ${region} region. An agent receives only the body, with the parameter's default in place:
# Support replies
You answer Acme's customers in the eu region. - It starts on the first line with a line of exactly
---, and ends at the next line of exactly---. A leading byte-order mark is ignored for this, and kept in the digest. - It is one YAML mapping, read by the YAML rules below. Anything else is
invalid-metadata. - A
---that isn't closed isinvalid-metadata, and its lines are read as body. - An included or inherited document keeps its own front matter. Its parameters, extensions and references apply to its own content, and are never merged into the document that includes it.
Every key
These are the keys the first edition defines. A key not in this table is kept, has no effect, and reports nothing, so tools can add their own.
| Key | Type | What it does | What the check reports |
|---|---|---|---|
spec | string "1" | The edition the document is written in. Absent means "1"; the integer 1 reads as "1". The service stores it with each version. | Any other value: unsupported-format (error). |
id | string (a URI) | The document's own URI. It is not a digest, and the service doesn't use it to find the instruction. | Not a string: invalid-metadata. |
version | string | The version label: the author's own name for this revision, such as "2026-11". It is not the service's version number (v1, v2…), which a release assigns; a release neither reads nor changes it. | Not a string: invalid-metadata. |
title | string | A descriptive title. The service names a version by the body's first `# ` heading, and uses title only when there is none. `instruction push` uses it as a new instruction's title when --title is not given. | Not a string: invalid-metadata. |
description | string | A descriptive summary. It is not the instruction's description in the service, which `instructions_update` sets. | Not a string: invalid-metadata. |
language | string (BCP 47) | The language the document is written in, such as en or de-CH. | Not a string: invalid-metadata. |
tags | list of strings | Descriptive tags. They are not the instruction's tags in the service, which `instructions_create` and `instructions_update` set and deployment rules select by. | Not a list of strings: invalid-metadata. |
license | string (SPDX) | The document's licence, such as CC-BY-4.0. It is not the instruction's licence in the service, which `instructions_update` sets. | Not a string: invalid-metadata. |
parameters | mapping | Parameter names to typed declarations: { type, required, default, example, description, source, values }. See Parameters. | Not a mapping: invalid-metadata. A bad declaration: parameter-invalid. A Specification 1.1 list: instruction.md/legacy-syntax. |
extends | list of records | The bases this document inherits, in order: { uri, as, mode, sha256, version, select, with }. Each as is unique. See Includes, inheritance and extensions. | Not a list, or a record without uri and as: invalid-metadata. A repeated as: duplicate-id. |
extensions | mapping | Local aliases bound to an exact extension: alias: { id, version, required }. A kind such as charts:metric uses the alias charts. See Includes, inheritance and extensions. | Not a mapping, or a binding without id and version: invalid-metadata. An alias used but not declared: extension-unavailable. |
references | mapping | Named reference records ({ uri, select, mode, version, sha256, required }) that body references use by name. See Inline references, links and annotations. | Not a mapping: invalid-metadata. |
resolvers | mapping | Adapter and account aliases a resolver uses, such as contacts: { adapter: directory, account: personal }. Credentials stay with the host. | Not a mapping: invalid-metadata. |
exports | mapping | Named targets for an explicit compiler: adapter, profile, bindings to body blocks, and an optional required flag. | Not a mapping: invalid-metadata. |
presentation | mapping | Theme and style tokens, and optional stylesheet or component references. Presentation never changes what a rule means. | Not a mapping: invalid-metadata. |
requires | list of strings | Extension aliases the document needs beyond the ones its blocks use. Never a grant. | Not a list: invalid-metadata. An alias extensions doesn't declare: extension-unavailable. |
integrations | mapping | The author's integrations policy: { allowed, servers }. It narrows which connected objects and tools may be used, and never widens the host's. See Tools, skills, agents and services. | Another key or shape: invalid-metadata. |
host-integrations | mapping | The serving host's policy, the same shape. instruction.md adds it when it serves a version, as lines outside the signed bytes. Never write it yourself. See Tools, skills, agents and services. | In a source you check or release: host-matter-authored (error). |
requires and integrations never grant anything. A host decides what a document may use; these keys can only say that the document needs an extension, or narrow what it may connect to.
The version label and published versions
The front matter's version is the version label: a name the author gives this text, such as "2026-11" or "2.3". It is a string, so quote a value YAML would read as a number (version: 1.2 is invalid-metadata).
It is not the version an agent follows. Each release in instruction.md is a new published version, numbered v1, v2 and so on by the service, with its own digest and signature. A release doesn't read the version label, change it or require it, and two published versions may carry the same label. Pin a version by its number or a ref (The model), and a digest by sha256 on a reference record (Includes, inheritance and extensions), never by the label.
Title and name
The service reads a name from a text the same way each time: the body's first # heading after the front matter, cut to 200 characters, else the front matter's title. spec_validate returns the name it finds this way as title.
- A new instruction.
instructions_createtakes thetitleyou give it, else the name read from its text, else "Untitled instruction".instruction pushgives it the front matter'stitlewhen you don't pass--title, so a pushed file is named by its front matter, not its heading, until its first release. - Each release. The version is named by the name read from its text, else the instruction's current title, and the instruction takes that name as its title too.
The instruction's title, description, tags and licence in the service are its details, changed with instructions_update. Changing them doesn't change the text. The front matter's description, tags and license never change them, and when the text has a heading or a title, the next release names the instruction from it again, replacing a title set with instructions_update.
YAML rules
Front matter, backmatter and every structured body (a data, config or other YAML block) use YAML 1.2's Core Schema, restricted to values JSON can hold:
- A repeated key is an error, and so is a key that isn't a string.
- Anchors, aliases and custom tags (
!tag) are errors. No constructor ever runs. - Numbers must be finite:
.infand.nanare errors. - A second YAML document (a
---line inside the region) is an error. - Dates stay strings.
2026-11-20,on,yesandnoare read as text, never as a timestamp or a boolean.
A JSON body (format=json) is JSON without repeated keys.
Backmatter
Backmatter is YAML after the body, for the people who keep the document:
# Support replies
MUST: quote the refund period from :cite[the handbook]{ref=handbook}.
---
authors: [Sam Lee]
owners: [support-leads]
review: { next: "2027-05-01" }
history:
- { date: "2026-11-20", summary: Add the refund period }
sources:
- { id: handbook, title: Support handbook, uri: "https://acme.example/handbook" } # Support replies
MUST: quote the refund period from the handbook (cite; handbook). A --- line opens backmatter only when all of these hold:
- It is exactly
---, at column zero, at the top level of the body: not in code, a container, a quote, a list or an HTML block. - A blank line comes before it.
- The first line after it that is neither blank nor a YAML
#comment starts with one of the known keys below and a colon.
Then everything after it, to the end of the file, is one YAML mapping. There is no closing ---: a backmatter that ends with one is Specification 1.1's end matter, an instruction.md/legacy-syntax error that Upgrade from Specification 1.1 converts. An empty or invalid mapping is invalid-metadata; the region is never read as body instead.
| Known first key | What it records |
|---|---|
authors | Who wrote the document. |
owners | Who keeps it right. |
review | Its review state, such as { next: "2027-05-01" }. |
history | Its change history, such as a list of { date, summary }. |
sources | The sources it draws on: a list of { id, title, uri }. :cite[Label]{ref=id} cites one. |
approvals | Who approved it. |
notes | Notes for the people who maintain it. |
test_results | References to test artifacts, such as { uri, source_digest }. |
Other keys may follow the first one and are kept. Backmatter never changes how the body above it is read or resolved.
A break that stays a break
A --- not followed by a known key is an ordinary thematic break, delivered with the body. To write a break before a line that looks like a key, use *** or ___, or escape it as \---:
# Support replies
MUST: greet the customer by name.
---
Notes: this line is body text, because "Notes" is not a backmatter key.
***
owners: this line is body text too, because *** never opens backmatter. # Support replies
MUST: greet the customer by name.
---
Notes: this line is body text, because "Notes" is not a backmatter key.
***
owners: this line is body text too, because *** never opens backmatter. Sources and citations
sources in the backmatter is a list, each record with an id, a title and a uri. A sources that isn't a list is invalid-metadata. In the body, :cite[label]{ref=id} cites one of them, and is delivered as label (cite; id), as in the backmatter sample above.
A citation adds attribution, never the source's contents: the agent receives the label and the id, not the text at the address. A ref that names no recorded source is a warning (reference-optional), and the citation is delivered in the same form, with that id. The other inline forms are on Inline references, links and annotations.
Comments
An HTML comment is a note for the people who edit the document:
# Support replies
<!-- Whole-line comment: the line goes. -->
MUST: greet the customer <!-- an inline comment --> by name.
<!--
A comment over
several lines.
-->
Write `<!-- this stays -->` in a code span to show the syntax. # Support replies
MUST: greet the customer by name.
Write `<!-- this stays -->` in a code span to show the syntax. - A comment's bytes are removed wherever it is. A line that held only a comment is removed with it; text before and after a comment on the same line stays, spaces included.
- A comment may span several lines. One that is never closed runs to the end of the file, with the warning
comment-unclosed. - Comments are never read for rules, blocks, references or parameters.
- Comment-looking text inside a code span, a code block, a structured body, an
exampleor averbatimblock stays as written and is delivered.
What is never delivered
The delivered text is the body only. These never reach a model:
- The front matter, including
title,descriptionand every other key. Itsparametersgive values to the body, and nothing else of it is inserted as guidance. - The backmatter, including
notesandsources. - Comments.
- A block's
id,classandstyle, and a layout block's presentation attributes. A block'stitleis delivered as its generated heading (a rule's, on its attribute line). See Rules and blocks. - The
host-integrationslines the service adds when it serves a version (below).
What is delivered, line by line, is on What an agent receives.
The host's lines
When instruction.md serves a version under an organization's integrations policy, it adds that policy as host-integrations lines right after the front matter's opening ---, or in a front matter of their own when the document has none. They sit outside the author's bytes: the authored digest and the author signature are checked against the text without them (Signing and verification). A source you write never holds them. spec_validate, instructions_validate and a release refuse one that does:
---
host-integrations:
allowed: ["https://orders.example.com/mcp"]
---
MUST: greet the customer by name. {
"ok": false,
"diagnostics": [
{
"code": "host-matter-authored",
"severity": "error",
"message": "host-integrations is the host's: it is added when the instruction is served, so a source never holds it",
"line": 1,
"remedy": "Remove host-integrations; to narrow what this instruction uses, write integrations"
}
],
"spec": "1",
"requires": [
"guidance"
],
"title": null,
"validator": "instruction.md"
} instruction validate doesn't check for these lines, so a file it passes can still be refused here. To narrow what your own document may use, write integrations instead (Tools, skills, agents and services).
If the front matter doesn't read
Each mistake below, and what instruction validate support.md prints for it:
A list where a mapping is expected
---
parameters:
- name: region
type: string
---
MUST: answer. INVALID support.md
line 1: the front matter's parameters is a mapping [invalid-metadata]
line 2: a Specification 1.1 parameter list: this edition declares parameters as a mapping, name: { type: … } [instruction.md/legacy-syntax] A key repeated
---
title: Support
title: Support replies
---
MUST: answer. INVALID support.md
line 2: the front matter is not valid YAML: Map keys must be unique [invalid-metadata] A version label written as a number
---
version: 1.2
---
MUST: answer. INVALID support.md
line 1: the front matter's version is a string [invalid-metadata] An edition this reader doesn't know
---
spec: "2"
---
MUST: answer. INVALID support.md
line 1: spec: "2" is not a format this reader knows; it reads spec: "1" [unsupported-format] Tags as one string
---
tags: support, email
---
MUST: answer. INVALID support.md
line 1: the front matter's tags are a list of strings [invalid-metadata] An unclosed front matter
---
title: Support replies
MUST: answer. INVALID support.md
line 1: the front matter is not closed: it ends with a line of exactly --- [invalid-metadata] Every diagnostic code, with the fix the language service offers, is on Diagnostics and fixes. Still stuck? Ask support.