Type System

Types in MDZ are contracts for tooling and semantic hints for LLMs—not runtime enforcement.

Philosophy

Unlike traditional programming languages, MDZ types are:

  • Descriptive — They document intent for humans
  • Interpretive — They guide LLM behavior
  • Tooling-friendly — They enable validation and autocomplete
  • Build-time checked — Contract compatibility verified before runtime

Types as Contracts

Types enable tooling to check that modules fit together correctly:

<!-- In skill A -->
$validator: $Task

<!-- In skill B (referencing A) -->
USE ~/skill/a TO /validate/ WITH:
  validator: 42  ← Error: $Number where $Task expected

This mismatch is caught at build time—before the LLM ever sees it. Without MDZ, you'd discover it at runtime with a confused LLM.

Defining Types

Semantic Types

Natural language descriptions that help LLMs understand values:

$Task: /any task that an agent can execute/
$Hypothesis: /a testable prediction about what will solve the problem/
$Observation: /data collected from running an experiment/

Enum Types

Constrained sets of string values using the union operator (|):

$Strategy: "fast" | "thorough"
$Result: "confirmed" | "refuted" | "inconclusive"
$Priority: "low" | "medium" | "high" | "critical"

Tuple Types

Tuples combine multiple types:

$TaskWithPriority: ($Task, $Priority)
$Transform: ($Task, $Strategy)

Array Types

Collections using the array suffix ([]):

$Tasks: $Task[]
$Transforms: ($Task, $Strategy)[]

Function Types

Lambda expressions using the arrow operator (=>):

$pathGenerator = $n => `output-$n.md`
$formatter = ($item, $index) => `$index. $item`

Using Types

Typed Declarations

Use the type annotation (:) to declare variable types:

$task: $Task                           <!-- required parameter -->
$result: $Result = "pending"          <!-- typed with default -->
$transforms: $Task[]                   <!-- array of tasks -->

What Tooling Checks

The MDZ validator performs static analysis on types:

  • Undefined types — Using $Foo without defining it
  • Contract mismatches — Passing wrong type across skill boundaries
  • Typos — $Numbr flagged with "did you mean $Number?"

The LLM sees the types as you wrote them—$Task stays $Task. Types are signals to both tooling and the LLM, not something that gets transformed.

Built-in Types

These types are implicitly available:

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

Best Practices

  • Use descriptive names: $Hypothesis not $H
  • Write clear descriptions: think "what would help an LLM understand this?"
  • Use enums for fixed sets of options
  • Define types at the top of your skill in a ## Types section