Syntax Reference

Complete reference for MDZ syntax, from document structure to control flow.

Document Structure

An MDZ document is a valid markdown file with these extensions:

---
frontmatter (YAML)
---

# Heading

Body content with MDZ constructs

Frontmatter

Required and optional fields in YAML frontmatter:

---
name: skill-name              # Required: identifier (kebab-case)
description: When...          # Required: trigger description
---

Note: Dependencies can be declared in uses: or inferred from links in your document.

Types

Type Definitions

Types provide semantic hints about values:

$TypeName: /natural language description/

$Task: /any task that an agent can execute/
$Strategy: "accumulate" | "independent"
$Result: "success" | "failure" | "pending"

Type Forms

  • Semantic type: $Task: /any executable instruction/
  • Enum type: $Strategy: "fast" | "thorough" (variants separated by union operator |)
  • Tuple type: ($Task, $Strategy)
  • Array type: $Task[] (uses array suffix)
  • Function type: $fn = $x => expression (uses arrow operator)

Variables

Variables use the dollar sigil ($) prefix. The type annotation (:) is optional:

Variable Declaration

$name: $Type = value   <!-- typed declaration -->
$name = value              <!-- simple declaration -->

Examples

$current: $FilePath = $SolutionPath(0)
$iterations = 0
$result: $ValidationResult

Lambda Expressions

Functions use the arrow operator (=>):

$functionName = $param => expression
$functionName = ($a, $b) => expression   <!-- multiple params -->

$solutionPath = $n => `output-$n.md`

Semantic Type Annotations

When a variable needs a semantic description rather than a named type, use the semantic type syntax:

## Input
$skillPath: $String  <!-- path to the skill -->

## Context
$skill: /the loaded and parsed skill AST from $skillPath/

## Workflow
1. Load skill source from $skillPath
2. Parse into $skill AST
3. FOR $statement IN $skill.statements
   Process $statement
   END

This pattern makes semantic transformations explicit and avoids confusion about where properties come from.

Links

Links reference other files using path syntax. The type is inferred from the folder:

Link Syntax

  • ~/skill/name — Link to a skill in the skill/ folder
  • ~/agent/name — Link to an agent in the agent/ folder
  • ~/tool/name — Link to a tool in the tool/ folder
  • #section — Anchor to a section in the current file
  • ~/skill/name#section — Link with anchor to a specific section

Folder Conventions

The folder in the path determines the reference type:

  • agent/ — Agents for delegation
  • skill/ — Reusable skill modules
  • tool/ — Tool integrations

Examples

~/skill/code-review           <!-- skill reference -->
~/agent/architect             <!-- agent reference -->
~/tool/browser                <!-- tool reference -->
#validation-prompt            <!-- local anchor -->
~/skill/review#checklist      <!-- link with anchor -->

Section Anchors

Section names are derived from headings by:

  1. Converting to lowercase
  2. Replacing spaces with hyphens
  3. Removing special characters
## Validate Prompt
→ #validate-prompt

## 2. Execute Phase
→ #2-execute-phase

Semantic Markers

The /content/ syntax marks content for LLM interpretation. There are three forms:

Inline Semantic Markers

Mark inline content that the LLM should interpret contextually:

/appropriate location for this output/
/determine best strategy for $task/

Variables are expanded before interpretation:

/the path for candidate $n/
<!-- First $n is resolved, then LLM interprets -->

Inferred Variables

Use $/name/ for variables the LLM infers and tracks without explicit declaration:

$/current-hypothesis/
$/best-candidate/

The LLM maintains these values implicitly based on context.

Semantic Type Annotations

Use /description/ as a type annotation for variables that need semantic descriptions:

$skill: /the loaded and parsed skill AST/
$result: /outcome of the validation step/

Control Flow

For Loop

Iterate over a collection using the collection operator (IN):

FOR $item IN $collection
  Process $item
  Next step
END

With destructuring:

FOR ($task, $strategy) IN $transforms
  Execute $task with $strategy
END

While Loop

Loop with a condition. The DO keyword delimits the condition:

WHILE /condition/ AND $iterations < 5 DO
  Perform iteration
  Update state
END

Conditional

Branch with IF/THEN and optional else clause:

IF $condition THEN
  Do this
ELSE
  Do that
END

IF $strategy = "accumulate" THEN
  Validate incrementally
ELSE
  Collect all candidates
END

GOTO

Jump to a section anchor:

GOTO #validation-prompt
GOTO ~/skill/helper#setup

Composition

USE (Skill Invocation)

Invoke a skill to perform a task:

USE ~/skill/code-review TO /check style/

USE ~/skill/orchestrate TO /coordinate tasks/

WITH Clause (Passing Templates)

Pass a section template when invoking:

USE ~/skill/mapper TO /process items/ WITH #item-prompt

EXECUTE (Tool Invocation)

Execute a tool to perform an action:

EXECUTE ~/tool/browser TO /take screenshot/

EXECUTE ~/tool/file-system TO /read config/

DELEGATE (Agent Delegation)

Delegate to an agent for autonomous work:

DELEGATE /task description/ TO ~/agent/architect

DELEGATE /research phase/ TO ~/agent/explorer

Pattern Summary

  • USE — Invoke skills for reusable workflows
  • EXECUTE — Run tools for external actions
  • DELEGATE — Spawn autonomous agents
  • GOTO — Jump to section anchors
  • WITH — Pass template sections

Conventional Sections

While not required, these sections are conventional:

## Types
Type definitions

## Input
Input parameter declarations

## Context
Contextual variable declarations

## Workflow
Main execution steps

## [Section Name]
Reusable prompts/sub-sections