# Markform

> 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.

- Skill: `jlevy/markform` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jlevy/markform`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jlevy/markform/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: jlevy (https://skillmd.com/u/jlevy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/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 |

```bash
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:

```bash
# 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`