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.
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
Install the .vsix file
From a terminal, in the folder that holds the file:
Shellcode --install-extension vscode-instruction-md-0.2.0.vsixOr run Extensions: Install from VSIX… from the Command Palette and pick the file. In VSCodium, use
codium --install-extensionwith the same file.Check that it is installed
Shellcode --list-extensions --show-versions | grep instruction-mdIt prints:
Open an instruction
Open a Markdown file whose front matter has
spec: "1", or one namedinstruction.mdor*.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."
{
"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:
---
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.
::: Fix the underlined line
:::polcyis 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, pressCtrl+.(Cmd+.on macOS) and choose Write :::policy. The diagnostic goes away.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.See what an agent receives
Run instruction.md: Show Delivered Text from the Command Palette (
Ctrl+Shift+P). A read-only document namedhouse-style.delivered.mdopens: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.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.
{
"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/**/*.mdmatches every Markdown file under anyagentsfolder, whileagents/**/*.mdmatches 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,trueandfalse, 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.
{
"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#idtarget jumps to what declares that id: a directive'sid=, a rule's[id]or a heading's{#id}. Targets are the values ofref=,target=,server=,sandbox=andschema=, 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.
Sign the stdio server in once
It needs Node.js 20.19 or later.
npxfetches theinstruction.mdpackage, so nothing is installed globally. The sign-in opens your browser, is stored for your user and is used by every workspace:Shellnpx -y instruction.md loginPrint the settings
Shellnpx -y instruction.md connect --host vscode instruction://acme/support-agent@stableReplace
acme/support-agent@stablewith your instruction's owner, name and ref.@stableis a ref you create;@latestfollows each release (Refs).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_replaceandinstructions_validatework on them. Only.mdfiles inside the roots are read or written, and a file is changed only byinstructions_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 resourceinstruction://currentand the promptfollow.
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.
| Setting | Type | Default | Effect |
|---|---|---|---|
instruction-md.detect | "auto" | "always" | "never" | "auto" | How the extension recognises an instruction document. |
instruction-md.files | array | ["**/instruction.md","**/*.instruction.md"] | Glob patterns of Markdown files that are instructions by name (the formatter is registered for these). |
instruction-md.preview.params | object | {} | 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.enabled | boolean | true | Report 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.
| Command | Id | Where | Key |
|---|---|---|---|
| instruction.md: Open Preview | instruction-md.openPreview | Command Palette | |
| instruction.md: Open Preview to the Side | instruction-md.openPreviewToSide | Command Palette, editor title bar, editor context menu | Ctrl+K I (Cmd+K I on macOS) |
| instruction.md: Show Delivered Text | instruction-md.showDelivered | Command Palette, editor context menu | |
| instruction.md: Validate | instruction-md.validate | Command Palette | |
| instruction.md: Format Instruction | instruction-md.format | Command 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 ordata:URLs, and noconnect-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.