لم تُترجم هذه الصفحة بعد.

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 name become 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= becomes id=, and an attribute value @kind/name becomes #name.
  • No variants. :::when, :::unless and :::otherwise are 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 :::example block. 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: … }, and spec becomes "1". The closed end matter (a --- … --- block at the end) becomes the backmatter, which runs to the end of the file; its changelog becomes history, approved becomes approvals, and a source's url becomes uri.
  • 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 kindThis edition
assetresource
channelservice
endpointservice
humanperson
knowledgesource
mediaresource
peeragent
runtimesandbox
agentthe same name
configthe same name
datathe same name
evalthe same name
imagethe same name
mcpthe same name
policythe same name
skillthe same name
sourcethe same name
testthe same name
workflowthe 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:

On1.1This edition
every kindnameid
skillwhentrigger
mcpendpointsrc
agentendpointsrc
outputformatresponse-format
includeurisrc
includeidas
imagedigestsha256

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

Specification 1.1
# 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.
:::
After the conversion
# 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.
:::
The conversion's notes
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, :::unless or :::otherwise;
  • a block that names itself with name= (apart from param and tool);
  • 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:

Specification 1.1
---
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:

instruction validate
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:

After the conversion
---
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.md package, npm i instruction.md (0.11.0 or later).

Upgrade one instruction in the editor

One quick fix converts the whole document.
  1. Open the instruction

    Problems shows an error on each 1.1 line. With Developer mode on, it is instruction.md/legacy-syntax with the line's message; with it off, it reads "Part of this is written in an older format. Update it to the current one."

  2. 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.

  3. 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.

  4. 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.

The call
{
  "name": "spec_fixes",
  "arguments": { "content": "<the 1.1 text>", "code": "instruction.md/legacy-syntax" }
}
The answer
{
  "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:

Apply it
{
  "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
// 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);
Convert a folder, then check it
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.

Stored instructions
# 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> prints ok for the file, or instructions_validate answers "ok": true.
  • Problems shows no instruction.md/legacy-syntax.
  • spec_deliver, or instruction 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

Last checked against the product:

Was this page helpful? Report a problem