PLAYBOOK.md for VS Code
Syntax highlighting, validation, and snippets for PLAYBOOK.md workflow files.
Install
This extension is not yet published to the VS Code Marketplace. To install locally:
npm install
npm run build
npx @vscode/vsce package
code --install-extension playbook-md-0.1.0.vsix
Features
- Syntax highlighting for
.playbook.md files -- section headers, directives, variable interpolation, input declarations, branching, and fenced code blocks
- Injection grammar that highlights PLAYBOOK.md syntax inside standard Markdown files
- Snippets for quickly scaffolding playbooks, steps, inputs, branches, and directives
- Real-time validation with fatal errors and warnings based on the PLAYBOOK.md spec
- CodeLens annotations above titles, steps, inputs, and artifacts for at-a-glance structure
- Hover information for variables, directives, and step headings
- Language configuration with auto-closing pairs, folding by heading, and comment toggling
Validation
The extension validates your playbook in real-time (on open, save, and as you type with 500ms debounce) and reports diagnostics in the Problems panel.
Fatal Errors
| Code |
Description |
| F1 |
No # Title heading found |
| F2 |
No ## STEP N: Title heading found |
| F3 |
Duplicate input names |
| F4 |
Document exceeds 200KB |
| F5 |
Empty or whitespace-only document |
Warnings
| Code |
Description |
| W1 |
Non-sequential step numbers (not 1, 2, 3...) |
| W2 |
Malformed input line in INPUTS section |
| W3 |
Unknown artifact type |
| W4 |
Undeclared branch variable |
| W5 |
Invalid elicit type (not input, confirm, or select) |
| W6 |
Undeclared interpolation variable |
| W7 |
Output name shadows an input variable |
CodeLens
Inline annotations appear above key sections to give you a structural overview:
- Title (
# My Playbook) -- shows step count, input count, and overall validity
- Steps (
## STEP N: Title) -- shows "Step N of M" and lists directives used (@output, @elicit, @tool, @prompt)
- Inputs (
## INPUTS) -- shows total inputs and how many are required
- Artifacts (
## ARTIFACTS) -- shows the declared artifact type
Hover over elements to see contextual information:
{{variable}} -- shows whether it is an input (with type, required status, description) or an output (with source step)@output(name) -- explains the directive and how to reference the captured value@elicit(type, "prompt") -- shows elicit type and prompt text@tool(conn.tool) -- explains external tool invocation@prompt(lib:id) -- explains external prompt prepending## STEP N: Title -- shows step summary with directives, output variable, branch variables, and position
Supported Syntax Elements
| Element |
Example |
| Playbook title |
# My Playbook |
| System prompt section |
## SYSTEM or ## SYSTEM PROMPT |
| Inputs section |
## INPUTS |
| Steps |
## STEP 1: Research |
| Artifacts section |
## ARTIFACTS |
| Input declarations |
- **topic** (string, required): The subject |
| Variable interpolation |
{{topic}} |
| Output directive |
@output(result) |
| Prompt directive |
@prompt(library/prompt-id) |
| Elicit directive |
@elicit(type: "prompt text") |
| Tool directive |
@tool(connection.tool_name) |
| Artifact directive |
@artifact(markdown) |
| Branching |
### IF, ### ELSE IF, ### ELSE |
| Conditions |
{{var}} == "value" |
Snippets
| Prefix |
Description |
pb-playbook |
Full playbook scaffold |
pb-step |
Step with title and output |
pb-input |
Input variable declaration |
pb-inputs |
INPUTS section with examples |
pb-system |
SYSTEM prompt section |
pb-branch |
IF/ELSE branching |
pb-output |
@output directive |
pb-artifact |
ARTIFACTS section |
pb-elicit |
@elicit directive |
pb-tool |
@tool directive |
Configuration
| Setting |
Default |
Description |
playbook-md.enableValidation |
true |
Enable/disable real-time validation |
playbook-md.enableCodeLens |
true |
Enable/disable CodeLens annotations |
playbook-md.enableHover |
true |
Enable/disable hover information |
License
MIT
| |
