jlevy/markform

Markform Agent Skill

Markform is structured Markdown for forms. Files combine YAML frontmatter with HTML comment tags to define typed, validated fields. Forms render cleanly on GitHub since structure is hidden in comments.

Getting Started

There are three ways to help a user get started with Markform:

1. Run an example automatically: markform examples copies bundled forms, then markform run <form> fills one end-to-end with an LLM. Quickest demo.
2. Agent-guided example tour: Walk the user through a specific bundled example step by step—copy it, inspect the structure, fill fields, validate, and export. Use markform examples --list to pick an example, then --name <id> to copy it.
3. End-to-end walkthrough playbook: Follow examples/markform-demo-playbook.md to design a research form from scratch, fill it with real data, validate, export, and browse. The most thorough tour of all Markform features.

API Key Setup

Automated filling (markform fill --model, markform run) requires an LLM API key. Set one of these environment variables (or add to .env):

• OPENAI_API_KEY — for OpenAI models (e.g., openai/gpt-4o)
• ANTHROPIC_API_KEY — for Anthropic models (e.g., anthropic/claude-sonnet-4-5-20250929)

Run markform models to see available providers and configured keys.

Bundled Examples

| Example | Type | Description | | --- | --- | --- | | movie-research-demo | research | Quick movie ratings lookup (IMDB, Rotten Tomatoes) | | simple | fill | Interactive demo of all field types | | twitter-thread | fill | Multi-stage content-to-Twitter-thread transformation | | movie-deep-research | research | Comprehensive movie analysis with multiple sources | | startup-deep-research | research | Startup intelligence: funding, team, market, press |

markform examples --list                        # See all examples
markform examples --list --format=json          # Structured output for agents
markform examples --name <id> --forms-dir ./    # Copy a specific example

What Markform Does

1. Structured Forms: Define typed fields (string, number, select, table, etc.) in Markdown with validation constraints
2. Role-Based Filling: Separate fields for humans (role="user") and AI agents (role="agent")
3. Incremental Filling: Fill fields one at a time with immediate validation
4. Agent-Driven Workflows: AI agents fill forms via CLI or programmatic API
5. Multi-Format Export: Export filled data as JSON, YAML, or Markdown

Core CLI Commands

| Command | Purpose | | --- | --- | | markform inspect <form> | Show form structure, progress, and issues | | markform validate <form> | Check for constraint violations and errors | | markform set <form> <field> "value" | Set a field value (auto-coerced) | | markform set <form> --values '{"k":"v"}' | Batch set multiple fields | | markform next <form> | Recommend the next field to fill | | markform fill <form> --interactive | Interactive prompts for user fields | | markform fill <form> --model <model> | AI agent fills form fields | | markform export <form> --format=json | Export values as JSON | | markform export <form> --format=yaml | Export values as YAML | | markform export <form> --format=markdown | Full rendered markdown (includes instructions) | | markform report <form> | Clean report markdown (values only, no instructions) | | markform schema <form> | Export JSON Schema for form structure | | markform dump <form> | Quick dump of current field values | | markform status <form> | Show fill progress per role | | markform docs | Show Markform syntax reference | | markform examples | Copy built-in example forms | | markform serve <form> | Web UI for browsing and editing |

Agent Workflow

When working with markform files:

1. Inspect first: markform inspect form.md to understand the form structure, see which fields exist, their types, constraints, and current fill progress
2. Check what’s next: markform next form.md to see which field should be filled next (respects priority, order, and role)
3. Set values: markform set form.md field_id "value" to fill fields one at a time, or use --values for batch updates
4. Validate: markform validate form.md to check all constraints are met
5. Export: markform export form.md --format=json to extract filled data

Setting Field Values

The set command is the primary way to fill fields. It auto-coerces values to the correct type:

# String fields
markform set form.md name "Alice Smith"

# Number fields (auto-coerced from string)
markform set form.md age 30

# Single select (by option ID)
markform set form.md rating high

# Multi select (JSON array of option IDs)
markform set form.md categories '["frontend","backend"]'

# Checkboxes (JSON object of {itemId: value})
markform set form.md tasks '{"research":"done","testing":"done"}'

# Table (append rows as JSON)
markform set form.md team --append '[{"name": "Alice", "title": "Engineer"}]'

# Batch set multiple fields
markform set form.md --values '{"name": "Alice", "age": 30, "rating": "high"}'

# Special operations
markform set form.md field_id --clear    # Clear a field value
markform set form.md field_id --skip     # Skip (mark as skipped)
markform set form.md field_id --abort    # Abort (mark as aborted)

Global Options

All commands support:

| Option | Description | | --- | --- | | --format <fmt> | Output format: console, json, yaml, plaintext, markform, markdown | | --verbose | Enable verbose/debug output | | --quiet | Suppress non-essential output | | --dry-run | Show what would be done without changes | | --overwrite | Overwrite existing field values |

File Conventions

| Extension | Purpose | | --- | --- | | .form.md | Markform source and filled forms | | .fill.json | Execution metadata (sidecar, auto-generated) | | .report.md | Filtered human-readable output | | .schema.json | JSON Schema export |

More Information

• Syntax reference: markform docs
• Full specification: markform spec
• API documentation: markform apis
• Example forms: markform examples
• End-to-end walkthrough: examples/markform-demo-playbook.md