Using MDZ in Your Project

Bridge the gap from playground examples to real-world adoption. Learn how to structure, validate, and integrate MDZ skills into your agent workflows.

Installation

Install the MDZ CLI globally to validate and work with skills: 

npm install -g @zenmarkdown/cli

Verify installation: 

mdz --version
# mdz 0.3.0

Workflow Overview

Using MDZ in a project follows three core steps:

  1. Write Skills - Author reusable MDZ skills for specific tasks
  2. Validate - Check syntax, types, and references before runtime
  3. Integrate - Use validated skills with agents and LLMs

Step-by-Step Tutorial

Follow this tutorial to create and use your first MDZ skill in a project.

1. Set Up Your Project

Create a new directory for your project and initialize it: 

mkdir my-agent-project
cd my-agent-project
mkdir skills

2. Create Your First Skill

Create skills/task-processor.mdz with this content (see syntax reference for details): 

---
name: task-processor
description: When processing tasks with validation and error handling
---

## Types

$Task: /a unit of work with inputs and expected outputs/
$Result: /successful completion or error details/

## Input

$task: $Task

## Context

$attempts = 0
$maxAttempts = 3

## Workflow

1. Validate $task inputs and requirements
2. WHILE $attempts < $maxAttempts DO
   Execute $task
   IF /execution succeeded/ THEN
     Return success result
   ELSE
     Increment $attempts
     Log error and retry strategy
   END
END
3. Return failure result with collected errors

## Error Handling

Handle common failure modes.
Invalid inputs.
Resource unavailability.
Timeout conditions.

3. Validate Your Skill

Validate the skill for syntax and type errors: 

mdz check skills/task-processor.mdz
# ✓ skills/task-processor.mdz is valid
#
#   Types: 2
#   Variables: 3
#   Dependencies: 0

If there are errors, fix them and re-run the check.

4. Compile the Skill

Compile the skill to generate metadata and validate thoroughly: 

mdz compile skills/task-processor.mdz
# Outputs the compiled skill with validation header

Save the compiled output for use: 

mdz compile skills/task-processor.mdz -o skills/task-processor.compiled.mdz

5. Use the Skill with an LLM

Copy the workflow section and use it in your LLM prompts. For example, in Claude Desktop: 

You are a task processor. Follow this process:

## Types
$Task: /a unit of work with inputs and expected outputs/
$Result: /successful completion or error details/

## Input
$task: $Task

## Context
$attempts = 0
$maxAttempts = 3

## Workflow
1. Validate $task inputs and requirements
2. WHILE $attempts < $maxAttempts DO
   Execute $task
   IF /execution succeeded/ THEN
     Return success result
   ELSE
     Increment $attempts
     Log error and retry strategy
   END
END
3. Return failure result with collected errors

## Error Handling
Handle common failure modes.
Invalid inputs.
Resource unavailability.
Timeout conditions.

Task to process: [PASTE YOUR TASK HERE]

Project Structure

Organize your skills in a dedicated directory structure for maintainability: 

your-project/
├── skills/
│   ├── core/           # Fundamental skills
│   │   ├── reasoning.mdz
│   │   └── planning.mdz
│   ├── domain/         # Domain-specific skills
│   │   ├── code-review.mdz
│   │   └── testing.mdz
│   └── orchestration/  # Multi-skill workflows
│       └── project-manager.mdz
├── agents/
│   └── my-agent.ts     # Agent that uses skills
└── package.json

Skills are loaded by referencing their file paths. For programmatic integration, you can implement your own skill discovery logic.

Writing and Validating Skills

Create skills for common patterns in your project: 

---
name: code-review
description: When reviewing code changes for quality and correctness
---

## Types

$CodeChange: /a set of file modifications with context/
$ReviewFocus: "security" | "performance" | "maintainability" | "correctness"
$Issue: /identified problem with severity and location/

## Input

$changes: $CodeChange
$focus: $ReviewFocus[] = ["correctness", "maintainability"]

## Context

$issues: $Issue[] = []

## Workflow

1. Analyze $changes for patterns and potential issues
2. FOR $area IN $focus
   Apply focused review for $area
   Add identified issues to $issues
   END
3. USE ~/skill/reasoning TO /generate summary/

Validate your skills to catch issues early: 

cd skills
mdz check code-review.mdz
mdz check domain/*.mdz  # Validate all domain skills

For more detailed validation and metadata generation, use compile: 

mdz compile code-review.mdz --verbose  # Show validation summary
mdz compile code-review.mdz --metadata  # Generate metadata JSON

Analyze dependencies between skills: 

mdz graph code-review.mdz --mermaid  # Output dependency graph

Parse skills to AST for programmatic use: 

mdz parse code-review.mdz > code-review.ast.json

Integration with Tools

Claude Desktop

Use MDZ skills by copying their workflow sections into Claude prompts: 

You are a senior developer conducting a code review. Follow this process:

## Types
$CodeChange: /a set of file modifications with context/
$ReviewFocus: "security" | "performance" | "maintainability" | "correctness"
$Issue: /identified problem with severity and location/

## Input
$changes: $CodeChange (provided below)
$focus: $ReviewFocus[] = ["correctness", "maintainability"]

## Workflow
1. Analyze $changes for patterns and potential issues
2. FOR $area IN $focus
   Apply focused review for $area
   Document identified issues
END
3. Generate review summary with prioritized recommendations

Code changes to review:
[PASTE YOUR CODE CHANGES HERE]

Custom Agent Frameworks

For programmatic integration, install the core library: 

npm install @zenmarkdown/core

Use the compile function to validate and process skills. See API docs for complete integration guide.

Copy-Paste Starting Point

Use this template to create your first project skill: 

---
name: task-processor
description: When processing tasks with validation and error handling
---

## Types

$Task: /a unit of work with inputs and expected outputs/
$Result: /successful completion or error details/

## Input

$task: $Task

## Context

$attempts = 0
$maxAttempts = 3

## Workflow

1. Validate $task inputs and requirements
2. WHILE $attempts < $maxAttempts DO
   Execute $task
   IF /execution succeeded/ THEN
     Return success result
   ELSE
     Increment $attempts
     Log error and retry strategy
   END
END
3. Return failure result with collected errors

## Error Handling

Handle common failure modes:
Invalid inputs.
Resource unavailability.
Timeout conditions.

Best Practices

  • Validate Early - Run mdz check in CI/CD pipelines
  • Skill Composition - Build complex workflows from simpler skills using links
  • Type Contracts - Define clear input/output types for reliability
  • Version Control - Track skill evolution alongside code changes
  • Testing - Test skills with representative inputs and edge cases

CI/CD Integration Example

Add to your .github/workflows/ci.yml: 

name: Validate MDZ Skills
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm install -g @zenmarkdown/cli
      - run: mdz check skills/**/*.mdz

Testing Skills

Test skills by validating with the CLI and checking for errors: 

# Test validation
mdz check skills/task-processor.mdz

# Test compilation with verbose output
mdz compile skills/task-processor.mdz --verbose

Next Steps