markform

name: markform description: >- 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:

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

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

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:

File Conventions

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