VS Code extension

This page is for developers who keep instructions in a repository and write them in VS Code. It shows how to install the instruction.md extension, what it checks and draws as you type, and how to let an agent in VS Code follow a released instruction beside it.

The extension reads the first edition of the specification (spec: "1", instruction/1). It runs the same reader, checks, resolver and formatter as the instruction CLI and the MCP server, so a document that passes here passes instruction validate, and its delivered text is what instruction deliver prints. It does not sign in, publish or release; that is the CLI and the web editor.

An instruction in VS Code: diagnostics with a quick fix beside the preview.

Before you start

  • VS Code 1.100.0 or later, desktop, on Windows, macOS or Linux. There is no web build yet (vscode.dev, github.dev). Editors built on VS Code with the same engine, such as VSCodium, should work but are not tested.
  • Nothing else. The extension carries what it needs: no Node.js, no CLI, no account. It never contacts a server.
  • The extension's id is {extensionId}. The current release is 0.2.0, under the MIT licence.

Install the extension

  1. Install the .vsix file

    From a terminal, in the folder that holds the file:

    Shell
    code --install-extension vscode-instruction-md-0.2.0.vsix

    Or run Extensions: Install from VSIX… from the Command Palette and pick the file. In VSCodium, use codium --install-extension with the same file.

  2. Check that it is installed

    Shell
    code --list-extensions --show-versions | grep instruction-md

    It prints:

    instruction-md.vscode-instruction-md@0.2.0
  3. Open an instruction

    Open a Markdown file whose front matter has spec: "1", or one named instruction.md or *.instruction.md. Its rules, blocks and parameters are highlighted, and the preview button appears in the editor's title bar.

Once the extension is listed, {installListed} will install it, and a repository can recommend it to everyone who opens it in .vscode/extensions.json. Until then that command answers "Extension 'instruction-md.vscode-instruction-md' not found."

.vscode/extensions.json
{
  "recommendations": [
    "instruction-md.vscode-instruction-md"
  ]
}

Try it on one document

Create house-style.md with this text. It has one mistake on purpose, :::polcy:

house-style.md
---
spec: "1"
title: House style
parameters:
  audience: { type: string, default: engineers }
---

# House style

Write for ${audience}.

MUST[second-person]: write in the second person.
BECAUSE: the reader is the one acting.

:::polcy{id=tone title="Tone"}
SHOULD: keep sentences short.
:::
  1. Fix the underlined line

    :::polcy is underlined as an error on line 15: ":::polcy is not a kind of this specification; it is kept as written, uninterpreted" (code {unknownKind.code}). Put the cursor on it, press Ctrl+. (Cmd+. on macOS) and choose Write :::policy. The diagnostic goes away.

  2. Open the preview

    Press Ctrl+K I (Cmd+K I). The preview opens beside the editor. Switch between rendered, delivered and source at its top.

  3. See what an agent receives

    Run instruction.md: Show Delivered Text from the Command Palette (Ctrl+Shift+P). A read-only document named house-style.delivered.md opens:

    house-style.delivered.md
    # House style
    
    Write for engineers.
    
    MUST: write in the second person.
    BECAUSE: the reader is the one acting.
    
    ### Policy: Tone
    
    SHOULD: keep sentences short.

    The rule's id ([second-person]) and the policy's fence are for people and tools. The agent reads plain rules under a heading, and ${audience} took its declared default.

  4. Try a parameter value

    Add this to your workspace settings (Preferences: Open Workspace Settings (JSON)):

    .vscode/settings.json
    {
      "instruction-md.preview.params": {
        "audience": "designers"
      }
    }

    The delivered text now starts with Write for designers.:

    house-style.delivered.md
    # House style
    
    Write for designers.
    
    MUST: write in the second person.
    BECAUSE: the reader is the one acting.
    
    ### Policy: Tone
    
    SHOULD: keep sentences short.

Which files are instructions

A Markdown file is an instruction when its front matter has a spec key, or when its path matches one of the instruction-md.files patterns (by default **/instruction.md and **/*.instruction.md). Other Markdown files, such as your README.md, are left alone. An untitled document counts by its front matter only.

Set instruction-md.detect to always to treat every Markdown file as an instruction, or to never to switch the extension off.

.vscode/settings.json
{
  "instruction-md.detect": "auto",
  "instruction-md.files": [
    "**/instruction.md",
    "**/*.instruction.md",
    "**/agents/**/*.md"
  ]
}

How a pattern matches:

  • A pattern without a / (*.prompt.md) matches the file name only, in any folder.
  • A pattern with a / matches the file's full path, not its path inside the workspace. Start it with **/: **/agents/**/*.md matches every Markdown file under any agents folder, while agents/**/*.md matches nothing. The formatter's patterns match the same way.
  • Patterns support **, *, ? and {a,b}, and are case-sensitive. On Windows, \ in a path counts as /.

The document stays a Markdown document: VS Code's own Markdown features and your other Markdown extensions keep working.

What the extension does

Highlighting

The grammar is generated from the specification's registry of kinds, keywords and attributes, so it cannot disagree with the reader. It colours directives and their closing fences (:::policy{id=privacy} … :::, ::person{id=owner}, extension kinds such as charts:metric), rules (MUST:, **MUST NOT:**, MUST[id] (if …):, also in a list item or a quote) and BECAUSE: reasons, alerts, attribute lists and #id targets, inline objects, wiki-links and embeds, footnotes, parameters, math, heading attributes and the backmatter. Structured bodies (:::config, :::workflow, :::data{format=json}) are coloured as YAML or JSON.

An example's body, a verbatim body and an extension's body stay quoted Markdown, because no rule is read there. Fenced code is never touched. Any colour theme works.

Diagnostics and quick fixes

After a short pause in typing, the extension runs the specification's checks, the same call as instruction validate, and lists each problem at its line and in the Problems panel. Each diagnostic has the source instruction.md and a stable code, such as unknown-kind, invalid-attributes, unclosed-directive, duplicate-id, reference-optional or parameter-optional. Hover over the line to read what the code means. Every code is on Diagnostics and fixes.

A line still written in Specification 1.1, the format before the first edition, is an error with the code instruction.md/legacy-syntax.

Severities are the specification's. An error means the document does not read as you wrote it (an unknown kind, an unclosed directive). A warning means it reads, but something it names is missing (an undeclared parameter, a reference to an id nothing declares), so the delivered text keeps it as written.

The quick fixes (Ctrl+., Cmd+. on macOS) come from the specification, and each clears the diagnostic it is for. Some of them:

Problem Code Example Fix
A misspelt kind unknown-kind :::polcy Write :::policy
An unknown attribute invalid-attributes :::policy{titel=Q} Write title, or remove titel=Q
A missing id invalid-attributes ::person{title="Alex Doe"} Give it the id alex-doe
An id used twice duplicate-id two {id=tone} Rename it tone-2
A missing closing fence unclosed-directive :::policy with no ::: Close it with :::
A misspelt reference reference-optional :person[Alex]{ref=#alx} Point it at #alex
An undeclared parameter parameter-optional Hello ${who}. Declare the parameter who
A missing footnote footnote-missing See[^n]. Define [^n]
An old format version unsupported-format spec: "1.1" Write spec: "1"
A line written in 1.1 instruction.md/legacy-syntax :::!policy Convert the document to this edition

When a diagnostic has exactly one fix, Auto Fix (Shift+Alt+., Cmd+Option+. on macOS) applies it. The conversion from 1.1 rewrites the whole document, so it is never applied automatically. A diagnostic with no fix says in its hover what to change. Upgrade from Specification 1.1 explains the conversion.

instruction.md: Validate checks the active document now. With no errors it says "instruction.md: no errors." (warnings don't count); otherwise it opens the Problems panel. To hide every diagnostic, set instruction-md.diagnostics.enabled to false.

Completion

Completion offers, from the document alone:

  • kinds after ::: and :: (a kind with required attributes inserts them as a snippet), and inline kinds after :;
  • attribute keys inside {…}, then their values: enums, true and false, and the ids a target may name;
  • references after @ and &, ids after # and [[#;
  • keywords where a rule starts, and alert types after > [!;
  • the front matter's and the backmatter's keys, and declared parameters after ${ and $;
  • a workflow step's tool arguments, from what the document's other steps pass the same tool;
  • / at the start of a line: the blocks of the web editor's Insert menu and its figures.

These are the same lists, in the same order, as the web editor's source view (both use one completions library). The extension has no account, so it never offers your workspace's people, agents or integrations: only what the document declares and names. Completion triggers on : { space = # ! " @ & $ / [ ,, and on Trigger Suggest (Ctrl+Space).

The preview

instruction.md: Open Preview to the Side (Ctrl+K I, Cmd+K I on macOS, or the button in the title bar) opens the specification's reference renderer beside the document. instruction.md: Open Preview opens it in the current column. It has three views:

  • rendered: the document as a reader sees it, with rules, policies, people and tools drawn as such;
  • delivered: the text the agent receives;
  • source: the document's text.

The preview follows your edits and your colour theme (light, dark and high contrast), and remembers the view you chose. There is one preview per document; opening it again brings it to the front. From the Command Palette, the preview and the delivered text open for any Markdown file, also one the extension does not recognise as an instruction. The preview takes string parameter values only; for a number, a boolean or a list it uses the document's default.

The delivered text

instruction.md: Show Delivered Text opens a read-only <name>.delivered.md with the instruction-text/1 profile, the same text instruction deliver prints:

  • the document's bases (extends) and includes (::include{src="./team.md#id=privacy" as=team}) are resolved from the files beside it, an open file as it stands in the editor, saved or not;
  • parameters take the values in instruction-md.preview.params, else the defaults the document declares, each with its declared type.
.vscode/settings.json
{
  "instruction-md.preview.params": {
    "audience": "designers",
    "max_words": 200,
    "strict": true,
    "channels": [
      "email",
      "chat"
    ]
  }
}

The view updates when you edit the document, a base or an include. Compare it with another file through Compare Active File With…. When the result is not complete, a warning says so: "a partial result" (a parameter or a reference nothing declares), or "it does not resolve, so a registry would not deliver it", with the error. Composition is on Includes, inheritance and extensions.

Go to Definition, references and hover

  • Go to Definition (F12) on a #id target jumps to what declares that id: a directive's id=, a rule's [id] or a heading's {#id}. Targets are the values of ref=, target=, server=, sandbox= and schema=, typed references such as :person[Alex]{ref=#owner}, and wiki-links such as [[#privacy|…]].
  • #alias/id (an id inside a base or an include) opens the file it comes from at that id. Navigation does not search the workspace.
  • Find All References (Shift+F12) on an id or a target lists everything in the document that names it.
  • Hover explains a kind, an attribute, a keyword, an alert, a reason, a #id, a parameter, a footnote, a front matter or backmatter key, and the codes of a line's diagnostics.

Formatting

instruction.md: Format Instruction applies the specification's conservative formatter, the same as instruction fmt: LF line endings, one final newline, and no trailing whitespace on a directive's own lines. It changes only the lines that need it, so your cursor and undo history stay. It is also the Format Document provider for files that match instruction-md.files (every Markdown file when instruction-md.detect is always). Other Markdown files keep their own formatter.

Let an agent in VS Code follow an instruction

The extension edits instructions; it does not deliver them. To let an agent in VS Code (Copilot Chat's agent mode, or any MCP client in the editor) follow a released instruction, connect it to instruction.md through the instruction command's stdio server, instruction mcp. VS Code speaks an older MCP than instruction.md's server (2026-07-28, stateless), so the stdio server speaks to the server on its behalf.

  1. Sign the stdio server in once

    It needs Node.js 20.19 or later. npx fetches the instruction.md package, so nothing is installed globally. The sign-in opens your browser, is stored for your user and is used by every workspace:

    Shell
    npx -y instruction.md login
  2. Print the settings

    Shell
    npx -y instruction.md connect --host vscode instruction://acme/support-agent@stable

    Replace acme/support-agent@stable with your instruction's owner, name and ref. @stable is a ref you create; @latest follows each release (Refs).

  3. Save them as .vscode/mcp.json

    .vscode/mcp.json
    // .vscode/mcp.json — VS Code speaks an older MCP than instruction.md, so it reaches it through this CLI's stdio server
    {
      "servers": {
        "instruction-md": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "-y",
            "instruction.md",
            "mcp",
            "--follow",
            "instruction://acme/support-agent@stable",
            "--url",
            "https://instruction.md/mcp"
          ]
        }
      }
    }
    // sign the bridge in once: npx -y instruction.md login
    // then, in agent mode: "read instruction://acme/support-agent@stable and follow it"

    Start the server from the file's Start link, or from MCP: List Servers. In agent mode, ask the agent to read the instruction and follow it.

The stdio server serves, on one connection:

  • the language's tools (spec_validate, spec_format, spec_outline, spec_fixes, spec_deliver, spec_convert, spec_explain), the same code the extension runs;
  • the instruction files in your workspace's roots as instructions: instructions_list, instructions_get, instructions_draft_replace and instructions_validate work on them. Only .md files inside the roots are read or written, and a file is changed only by instructions_draft_replace, never created;
  • signed in, instruction.md's tools, resources and prompts, as the server answers them;
  • with --follow, the followed instruction as the resource instruction://current and the prompt follow.

The roots are the folders given with --root DIR (repeatable), else the workspace folders VS Code reports, else the folder it starts in. Without --follow, it follows what the project's .instruction/follow.json names. --local keeps it offline: the workspace's files and the language's tools only. When instruction.md can't be reached, it says so on standard error and serves the workspace only. Every flag is on instruction command reference; the other hosts are on Connect an MCP client.

Settings and commands

These tables are read from the extension's manifest.

SettingTypeDefaultEffect
instruction-md.detect"auto" | "always" | "never""auto"How the extension recognises an instruction document.
instruction-md.filesarray["**/instruction.md","**/*.instruction.md"]Glob patterns of Markdown files that are instructions by name (the formatter is registered for these).
instruction-md.preview.paramsobject{}Parameter values for the delivered text (§12), by name, typed as a document declares them: a string, a number, a boolean or a list of strings. A document takes the ones it declares; one it declares with a default takes the default when no value is given here. The preview takes the string values.
instruction-md.diagnostics.enabledbooleantrueReport the specification's diagnostics (§18) and instruction.md's errors for lines still written in Specification 1.1.

A changed setting takes effect at once: diagnostics, open previews and delivered views are refreshed. Every setting can be set per user or per workspace.

CommandIdWhereKey
instruction.md: Open Previewinstruction-md.openPreviewCommand Palette
instruction.md: Open Preview to the Sideinstruction-md.openPreviewToSideCommand Palette, editor title bar, editor context menuCtrl+K I (Cmd+K I on macOS)
instruction.md: Show Delivered Textinstruction-md.showDeliveredCommand Palette, editor context menu
instruction.md: Validateinstruction-md.validateCommand Palette
instruction.md: Format Instructioninstruction-md.formatCommand Palette, editor context menu

The title bar button, the context menu entries and the key binding appear only for a file the extension recognises as an instruction (the context key instruction-md.active). The extension activates when a Markdown file opens.

Security and privacy

  • No network. The extension sends nothing anywhere: no telemetry, no account, no requests to instruction.md or anyone else.
  • The preview is locked down. It runs in a webview under a Content-Security-Policy of default-src 'none', with a nonce-bound script and stylesheet, images only from the extension or data: URLs, and no connect-src. The renderer draws no raw HTML, drops dangerous link protocols, and shows no images by default.
  • Files read. Besides the document, only the files it composes, and only from its own folder or below. A path with .. that leaves the folder is refused.
  • Nothing runs. Scripts, workflows, tests and configuration in a document are highlighted, never run. Restricted mode (an untrusted workspace) is fully supported.
  • Virtual workspaces are partly supported: highlighting, diagnostics and the preview work on any file system; completion, hover, navigation, quick fixes and the delivered text need files on disk or untitled documents.

Remove it

Run code --uninstall-extension {extensionId}, or choose Uninstall on the extension in the Extensions view. Your documents and settings are not changed; the instruction-md.* settings stay in your settings file until you delete them.

If it doesn't work

What you see Why What to do
Nothing is highlighted, no diagnostics The file is not recognised as an instruction Check the language mode is Markdown. Add spec: "1" to the front matter (the first line must be ---), rename the file *.instruction.md, or add a pattern to instruction-md.files. Check instruction-md.detect is not never.
Your README is checked as an instruction detect is always, or a pattern matches it Set instruction-md.detect to auto and narrow instruction-md.files.
Format Document uses another formatter The file doesn't match instruction-md.files Use Format Document With…, or run instruction.md: Format Instruction.
The delivered text is "a partial result" Something the document names is missing: a parameter with no value or default, an undeclared id, a base or include that isn't beside the document The warning names it. Declare it, give it a value, or move the file under the document's folder.
A parameter value doesn't show in the preview The preview takes string values only Numbers, booleans and lists apply in Show Delivered Text.
The preview says "Waiting for the document…" The webview did not start Close the preview and open it again. If it stays, look in Help ▸ Toggle Developer Tools for the error.
A diagnostic differs from the CLI's Different library versions Compare the extension's version with instruction --version and update the older one.
Still stuck Support, with the extension's version, your VS Code version and the smallest document that shows it.

Questions

Does the extension need an account or the internet?

No. It works offline and sends nothing. Only the stdio MCP server beside it talks to instruction.md, and only when you sign it in (above).

Can it publish a version?

No. Release with instruction push and instruction publish, or in the web editor. See The instruction CLI.

Will it read my old Specification 1.1 files?

It reports their 1.1 lines as errors with a quick fix that converts the whole document. See Upgrade from Specification 1.1.

Why does an agent in VS Code need the CLI?

VS Code speaks an older MCP than instruction.md's server, which speaks 2026-07-28 only. The CLI's stdio server bridges the two. See Connect an MCP client.

Last checked against the product:

Was this page helpful? Report a problem