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:

support-replies.md
---
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:

Delivered text
# 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 is invalid-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.

KeyTypeWhat it doesWhat the check reports
specstring "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).
idstring (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.
versionstringThe 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.
titlestringA 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.
descriptionstringA descriptive summary. It is not the instruction's description in the service, which `instructions_update` sets.Not a string: invalid-metadata.
languagestring (BCP 47)The language the document is written in, such as en or de-CH.Not a string: invalid-metadata.
tagslist of stringsDescriptive 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.
licensestring (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.
parametersmappingParameter 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.
extendslist of recordsThe 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.
extensionsmappingLocal 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.
referencesmappingNamed 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.
resolversmappingAdapter and account aliases a resolver uses, such as contacts: { adapter: directory, account: personal }. Credentials stay with the host.Not a mapping: invalid-metadata.
exportsmappingNamed targets for an explicit compiler: adapter, profile, bindings to body blocks, and an optional required flag.Not a mapping: invalid-metadata.
presentationmappingTheme and style tokens, and optional stylesheet or component references. Presentation never changes what a rule means.Not a mapping: invalid-metadata.
requireslist of stringsExtension 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.
integrationsmappingThe 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-integrationsmappingThe 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_create takes the title you give it, else the name read from its text, else "Untitled instruction". instruction push gives it the front matter's title when 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: .inf and .nan are errors.
  • A second YAML document (a --- line inside the region) is an error.
  • Dates stay strings. 2026-11-20, on, yes and no are 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.md
# 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" }
Delivered text
# 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 keyWhat it records
authorsWho wrote the document.
ownersWho keeps it right.
reviewIts review state, such as { next: "2027-05-01" }.
historyIts change history, such as a list of { date, summary }.
sourcesThe sources it draws on: a list of { id, title, uri }. :cite[Label]{ref=id} cites one.
approvalsWho approved it.
notesNotes for the people who maintain it.
test_resultsReferences 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 \---:

Markdown
# 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.
Delivered text
# 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:

Markdown
# 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.
Delivered text
# 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 example or a verbatim block 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, description and every other key. Its parameters give values to the body, and nothing else of it is inserted as guidance.
  • The backmatter, including notes and sources.
  • Comments.
  • A block's id, class and style, and a layout block's presentation attributes. A block's title is delivered as its generated heading (a rule's, on its attribute line). See Rules and blocks.
  • The host-integrations lines 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:

support-replies.md
---
host-integrations:
  allowed: ["https://orders.example.com/mcp"]
---

MUST: greet the customer by name.
spec_validate answer
{
  "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

support.md
---
parameters:
  - name: region
    type: string
---

MUST: answer.
Output
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

support.md
---
title: Support
title: Support replies
---

MUST: answer.
Output
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

support.md
---
version: 1.2
---

MUST: answer.
Output
INVALID  support.md
         line 1: the front matter's version is a string  [invalid-metadata]

An edition this reader doesn't know

support.md
---
spec: "2"
---

MUST: answer.
Output
INVALID  support.md
         line 1: spec: "2" is not a format this reader knows; it reads spec: "1"  [unsupported-format]

Tags as one string

support.md
---
tags: support, email
---

MUST: answer.
Output
INVALID  support.md
         line 1: the front matter's tags are a list of strings  [invalid-metadata]

An unclosed front matter

support.md
---
title: Support replies

MUST: answer.
Output
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.

Last checked against the product:

Was this page helpful? Report a problem