// Markdown-based form system for structured data collection by AI agents and humans. Inspect, fill, validate, and export .form.md files with typed fields and role-based workflows. Use when working with .form.md files, filling forms, validating fields, exporting data, or when the user mentions markform, forms, form filling, structured data, or field validation.
Markdown-based form system for structured data collection by AI agents and humans. Inspect, fill, validate, and export .form.md files with typed fields and role-based workflows. Use when working with .form.md files, filling forms, validating fields, exporting data, or when the user mentions markform, forms, form filling, structured data, or field validation.
allowed-tools
Bash(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:
Run an example automatically:markform examples copies bundled forms, then
markform run <form> fills one end-to-end with an LLM. Quickest demo.
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.
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)
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
Structured Forms: Define typed fields (string, number, select, table, etc.)
in Markdown with validation constraints
Role-Based Filling: Separate fields for humans (role="user") and AI agents
(role="agent")
Incremental Filling: Fill fields one at a time with immediate validation
Agent-Driven Workflows: AI agents fill forms via CLI or programmatic API
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:
Inspect first:markform inspect form.md to understand the form structure, see
which fields exist, their types, constraints, and current fill progress
Check what’s next:markform next form.md to see which field should be filled
next (respects priority, order, and role)
Set values:markform set form.md field_id "value" to fill fields one at a time,
or use --values for batch updates
Validate:markform validate form.md to check all constraints are met
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)
