Core Concepts

Understanding the fundamental ideas behind MDZ.

The LLM is the Runtime

This is MDZ's core assumption: the LLM is a capable machine that reads skills, interprets control flow, makes tool calls, and executes what the document says. There is no separate orchestration layer—the LLM handles execution.

MDZ provides the authoring format and validation tooling. The LLM + your agent framework handles the actual execution.

What Makes an LLM Language Different

Traditional programming languages catch typos and semicolons. An LLM language is less about syntactic correctness—the LLM can interpret messy input. Instead, it's about structural and systematic correctness:

Do all linked files actually exist?
Are there circular dependencies that would cause infinite loops?
Do types match across skill boundaries?
Is the overall system coherent?

A confused LLM hitting a broken ~/skill/nonexistent at runtime wastes tokens and time. MDZ catches these issues at build time, before the LLM ever sees the skill.

How it Works Under the Hood

MDZ uses a validator-first architecture. When you run mdz check or mdz compile, here's what happens:

1. Parsing

The source is parsed into an Abstract Syntax Tree (AST). The parser recognizes:

Frontmatter (name, description)
Type definitions ($Type: ...)
Variable declarations ($var: $Type = value)
Control flow (FOR, WHILE, IF/THEN/ELSE, END)
Links (~/skill/name, ~/agent/name)
Anchors (#section)
Semantic spans (positional) and inferred variables ($/name/)

2. Metadata Extraction

The compiler extracts structured metadata from the AST:

All type definitions and their schemas
All variable declarations with their types
All links and anchor references
Section anchors for cross-referencing

3. Dependency Graph

A dependency graph is built from inline links. Dependencies are inferred automatically from the links in your document. This enables:

Cycle detection across the skill graph
Visualization with mdz graph --mermaid
Understanding which skills depend on which

4. Validation

Multiple validation passes check for:

Type validation — Are referenced types defined?
Scope validation — Are variables defined before use?
Link validation — Do linked files exist?
Anchor validation — Do section anchors exist?
Contract validation — Do types match across boundaries?

5. Source = Output

Important: The compiler does not transform your source. The LLM sees exactly what you wrote. Validation happens at build time; the validated source goes directly to the LLM at runtime.

Skills

A skill is an MDZ document that defines agent behavior. Skills are:

Self-contained units of behavior
Composable through links
Documented through frontmatter
Validated by tooling before runtime

CAPS Keywords

Control flow and composition use uppercase keywords for visibility:

FOR, WHILE, DO, IF, THEN, ELSE, END, AND, OR, NOT, IN, BREAK, CONTINUE, RETURN, ASYNC, AWAIT
USE, EXECUTE, DELEGATE, TO, WITH, GOTO

This makes structure scannable and avoids conflicts with prose. The LLM interprets and executes these at runtime.

Types as Contracts

Types in MDZ are contracts for tooling, not runtime enforcement:

Types describe what values represent
Tooling checks that types match across module boundaries
The LLM uses types as semantic hints
There's no runtime type checking—just build-time validation

Built-in Primitives

MDZ includes built-in primitive types that don't need explicit definition:

$String — text content
$Number — numeric value
$Boolean — true or false

Prose First

MDZ skills read like natural language:

No cryptic syntax
Readable by non-programmers
Self-documenting
Valid markdown

MDZ extends markdown—it doesn't replace it. An MDZ file is valid markdown, viewable in any markdown renderer.