Upgrade from Specification 1.1
This page is for developers with instructions written in Specification 1.1, the syntax the editor, the CLI and the templates wrote before the first edition (instruction/1). It says what changed, why a 1.1 line is now an error, and how to convert one document in the editor or over MCP, or many at once with a script.
What changed
The first edition owes earlier drafts nothing: it reads a 1.1 construct as something else, or not at all. The conversion rewrites each construct as the one that means the same here:
- Blocks without
!.:::!kind{…},::!kind{…}and a section## !kind namebecome plain containers and leaves,:::kind{…}and::kind{…}. A set:::!kind[]becomes one leaf per member, from its table or YAML list. A structured kind's YAML loses the code fence 1.1 allowed around it. - Ids.
name=becomesid=, and an attribute value@kind/namebecomes#name. - No variants.
:::when,:::unlessand:::otherwiseare gone: every reader receives the same text. Each becomes a titled:::context, which every reader now receives. - Examples and references. An
EXAMPLE:paragraph becomes an:::exampleblock. A link with a sigil, such as[@On-call](principal://…), and[[kind/name]]become typed references such as:person[On-call]{ref=…}.](#kind/name)becomes](#name). - Metadata. A parameter list becomes a mapping,
name: { type: … }, andspecbecomes"1". The closed end matter (a---…---block at the end) becomes the backmatter, which runs to the end of the file; itschangelogbecomeshistory,approvedbecomesapprovals, and a source'surlbecomesuri. - Fences. When an inner fence is as long as its outer one, every container's fence is renumbered from its nesting: three colons innermost, one more for each level out.
These 1.1 kinds become this edition's:
| 1.1 kind | This edition |
|---|---|
asset | resource |
channel | service |
endpoint | service |
human | person |
knowledge | source |
media | resource |
peer | agent |
runtime | sandbox |
agent | the same name |
config | the same name |
data | the same name |
eval | the same name |
image | the same name |
mcp | the same name |
policy | the same name |
skill | the same name |
source | the same name |
test | the same name |
workflow | the same name |
A 1.1 workflow or config block gets dialect="agentd/workflow" (workflow) and dialect="agentd/config" (config). Those are agentd's dialects, so the workflow checks of instruction/workflow don't run on them; see Workflow node reference.
These attributes are renamed:
| On | 1.1 | This edition |
|---|---|---|
| every kind | name | id |
skill | when | trigger |
mcp | endpoint | src |
agent | endpoint | src |
output | format | response-format |
include | uri | src |
include | id | as |
image | digest | sha256 |
On a 1.1 block, an attribute this edition doesn't define on its kind is kept as x-<name>, an annotation that means nothing to a reader. overrides= is dropped: both rules are delivered. A param's source=prompt becomes source=input. A 1.1 data block whose body is a Markdown table becomes format=csv. :::tool{cap=…} becomes the mcp, skill or service block it granted on.
What has no counterpart here, such as a stream or a secret reference, is left as written and noted, so the check points at it.
Before and after: a :::when block
# Support replies
:::when{reader=agent plan=team}
Reply in under 100 words.
:::
:::unless{plan=team}
Offer the upgrade page once.
:::
:::otherwise
Reply in full sentences.
::: # Support replies
:::context{title="When reader is agent and plan is team"}
Reply in under 100 words.
:::
:::context{title="Unless plan is team"}
Offer the upgrade page once.
:::
:::context{title="Otherwise"}
Reply in full sentences.
::: line 3: :::when became a titled context: this edition delivers it to every reader, labelled "When reader is agent and plan is team"
line 7: :::unless became a titled context: this edition delivers it to every reader, labelled "Unless plan is team"
line 11: :::otherwise became a titled context: this edition delivers it to every reader, labelled "Otherwise" Every reader now receives all three contexts, labelled with their old conditions. Keep the ones that apply to everyone, and rewrite or delete the others. To give different readers different text, use parameters.
Why a 1.1 line is an error
This edition reads :::!human as no block at all and :::when as an unknown kind, kept as written. A release of such a text would deliver the 1.1 blocks to an agent as plain text. So instruction.md adds its own check, instruction.md/legacy-syntax, an error on each line written in 1.1, and a release refuses the text until it is converted. The check flags:
- a front-matter parameter list;
- a block or section with
!; - a
:::when,:::unlessor:::otherwise; - a block that names itself with
name=(apart fromparamandtool); - a reference link with a sigil;
- a closed end matter.
Each of these lines also gets the same fix, Convert the document to this edition, which converts the whole document. An EXAMPLE: paragraph, a [[kind/name]] and a ](#kind/name) are not flagged, since each is valid text here, but the conversion rewrites them too.
This 1.1 document:
---
spec: "1.1"
title: Support replies
parameters:
- name: product
type: string
required: true
---
# Support replies
You answer questions about ${product}.
:::!human{name=lead title="Support lead"}
:::
:::!mcp{name=tickets endpoint="https://mcp.example.com/tickets"}
:::
EXAMPLE: "Your refund is on its way."
Ask [@Support lead](principal://acme/lead) before a refund over €200.
---
changelog:
- "Initial version"
--- is flagged on these lines:
line 4: a Specification 1.1 parameter list: this edition declares parameters as a mapping, name: { type: … } [instruction.md/legacy-syntax]
line 14: a Specification 1.1 block: this edition writes a block without `!`, as :::kind{…} or ::kind{…} [instruction.md/legacy-syntax]
line 17: a Specification 1.1 block: this edition writes a block without `!`, as :::kind{…} or ::kind{…} [instruction.md/legacy-syntax]
line 22: a Specification 1.1 reference link: this edition writes :person[Label]{ref=…} [instruction.md/legacy-syntax]
line 27: a Specification 1.1 end matter: this edition's backmatter runs to the end of the file, with no closing --- [instruction.md/legacy-syntax] and converts to:
---
spec: "1"
title: Support replies
parameters:
product:
type: string
required: true
---
# Support replies
You answer questions about ${product}.
:::person{id=lead title="Support lead"}
:::
:::mcp{id=tickets src=https://mcp.example.com/tickets}
:::
:::example
"Your refund is on its way."
:::
Ask :person[Support lead]{ref=principal://acme/lead} before a refund over €200.
---
history:
- "Initial version" Before you start
- Who can do this: anyone who can edit the instruction's draft. A Contributor's edit lands as suggestions a Maintainer accepts.
- The conversion changes what agents receive once you publish, most of all where variants become contexts. Read the result before you publish it.
- For a script: Node.js 20.19 or later and the
instruction.mdpackage,npm i instruction.md(0.11.0 or later).
Upgrade one instruction in the editor
Open the instruction
Problems shows an error on each 1.1 line. With Developer mode on, it is
instruction.md/legacy-syntaxwith the line's message; with it off, it reads "Part of this is written in an older format. Update it to the current one."Apply the fix
Put the caret on one of those lines and press Ctrl+. (⌘. on a Mac), then choose Convert the document to this edition. The whole document is converted in one edit, so one undo takes it back.
Read the result
Look at each titled context that was a variant, and at any
x-attribute. Problems shows what is left to fix by hand.Publish
Publish the converted draft as the next version. Agents following the default ref receive it.
Upgrade over MCP
spec_fixes with the code instruction.md/legacy-syntax answers each flagged line (3 in the :::when sample above) with the same fix: one replace from the first character to the last, whose text is the converted document.
{
"name": "spec_fixes",
"arguments": { "content": "<the 1.1 text>", "code": "instruction.md/legacy-syntax" }
} {
"problems": [
{
"code": "instruction.md/legacy-syntax",
"severity": "error",
"message": "a Specification 1.1 variant: this edition delivers every reader the same text",
"line": 3,
"remedy": "convert the document to this edition",
"fixes": [
{
"title": "Convert the document to this edition",
"ops": [
{
"op": "replace",
"from": 0,
"to": 179,
"text": "<the converted text>"
}
]
}
]
}
],
"formatted": null
} Apply it to a stored draft with instructions_draft_edit, passing the draft's revision as expectedRevision, or send the converted text whole with instructions_draft_replace:
{
"name": "instructions_draft_edit",
"arguments": {
"instructionId": "acme/support-agent",
"expectedRevision": 14,
"ops": [{ "op": "replace", "from": 0, "to": 179, "text": "<the converted text>" }]
}
} Then check it with instructions_validate, and publish with instructions_publish.
Upgrade many files
The CLI has no upgrade command. instruction validate reports the 1.1 lines, and the conversion is the upgrade() function of the instruction.md package, the same one spec_fixes and the editor run. This script converts each file you give it in place, prints the conversion's notes, and fails when a file still has errors:
// upgrade.mjs: convert every 1.1 file given, in place, and say what to check.
// npm i instruction.md
import { readFileSync, writeFileSync } from "node:fs";
import { check, legacyLines, upgrade } from "instruction.md";
let failed = 0;
for (const file of process.argv.slice(2)) {
const text = readFileSync(file, "utf8");
if (!legacyLines(text).length) continue; // already in this edition
const { text: upgraded, notes } = upgrade(text);
writeFileSync(file, upgraded);
console.log(`upgraded ${file}`);
for (const n of notes) console.log(` line ${n.line}: ${n.message}`);
const errors = [...check(upgraded).filter((d) => d.severity === "error"), ...legacyLines(upgraded)];
for (const d of errors) console.log(` still to fix, line ${d.range?.start ?? d.line}: ${d.message}`);
if (errors.length) failed++;
}
process.exit(failed ? 1 : 0); node upgrade.mjs instructions/*.md
instruction validate instructions/*.md A file without 1.1 lines is left untouched. Commit before you run it, so git diff shows each change and git checkout takes one back.
For instructions stored on instruction.md, pull each draft, convert it, and push it back as the draft. instruction push --to replaces the draft; it doesn't publish. Publish each one after you have read it.
# ids as ins_…: an owner/name id would put a / in the file name
for id in ins_… ins_…; do
instruction pull "$id/draft" --out "$id.md"
node upgrade.mjs "$id.md"
instruction push "$id.md" --to "$id"
done Check it worked
instruction validate <file>printsokfor the file, orinstructions_validateanswers"ok": true.- Problems shows no
instruction.md/legacy-syntax. spec_deliver, orinstruction deliver <file>, shows the text an agent receives: check that each former variant reads right for every reader.
Undo
In the editor, undo the fix: it was one edit. A converted file is plain text; restore it from version control. A version you already published stays. Publish the old text again, or move the default ref back to the version before it with instruction refs <id> set latest <version id> (instruction versions <id> lists the ids) or instructions_refs_set. A ref that follows another ref, or that requires checks or a signature, may refuse the move.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
the text has 3 error(s) a release refuses; fix them first (spec_fixes helps) |
The draft is still in 1.1, or the conversion left an error | Run spec_fixes on the draft and apply the legacy fix, then fix what is left by hand |
:::!stream has no counterpart in this edition; rewrite it by hand (a note) |
That 1.1 kind has nothing to become | Rewrite the block in this edition's terms, or delete it |
x-… attributes after the conversion |
This edition doesn't define them on that kind | Delete them, or move what they said into the block's text |
version_conflict from instructions_draft_edit |
The draft changed after you read it | Read it again, ask for the fix again, and send it with the new revision |
| A former variant now reaches readers it shouldn't | Every reader receives every context | Rewrite it as one text for everyone, or use a parameter |
| Still stuck | Ask us |