MarkApiDown Skills: What the mad Skill Teaches Your Agent

A skill is a single markdown file that MarkApiDown installs into your AI agent’s config directory. When you open a file in api-docs/ or ask your agent to document an endpoint, the agent reads that file first — learning the MarkApiDown spec format, project layout, variable syntax, assertion rules, and tool preferences before it writes a single line. The result is a correctly structured spec on the first attempt, without any manual prompting on your part.

What a skill is

The mad skill is sourced from skills/mad/SKILL.md inside the MarkApiDown installation. When you run mad install skills, the CLI reads that file, adapts the frontmatter to match the target agent’s format, and writes it to the agent’s config directory. The content teaches the agent everything it needs to work with MarkApiDown specs autonomously. Skills are static files — they don’t run code or phone home. You can open, read, and commit the installed file like any other project file.

Where skills are installed

The installation path differs by agent. MarkApiDown writes the correct format automatically.

Agent	Installed file path	Format
Claude Code	`.claude/skills/mad/SKILL.md`	Standard SKILL.md with YAML frontmatter
Codex CLI	`~/.codex/skills/mad/SKILL.md`	Standard SKILL.md with YAML frontmatter
Antigravity	`.agents/skills/mad/SKILL.md`	Standard SKILL.md with YAML frontmatter
OpenCode	`.opencode/skills/mad/SKILL.md`	Standard SKILL.md with YAML frontmatter
Cursor	`.cursor/rules/mad.mdc`	`.mdc` with `globs: api-docs/*/.md`
GitHub Copilot	`.github/instructions/mad.instructions.md`	Markdown with `applyTo` frontmatter

Cursor and GitHub Copilot use their own file formats. MarkApiDown adapts the skill content automatically — Cursor receives an .mdc file scoped to api-docs/**/*.md, and Copilot receives an instructions file with an applyTo header. The skill content is identical; only the wrapper differs.

What the mad skill covers

The skill is organized into sections that map to the parts of the MarkApiDown workflow an agent needs to know.

Project layout

The skill teaches the agent the canonical api-docs/ directory structure:

api-docs/
├── mad.md                            # project config (name, default-env, timeouts)
├── _shared/env.md                    # base URLs and variables per environment
├── apis/<resource>/<method>-<slug>.md  # one file per endpoint
└── flows/<name>.md                   # multi-step pipelines

The agent knows to place new specs under apis/ and new pipelines under flows/, using the <method>-<slug>.md naming convention.

Endpoint file format

The skill defines the required YAML frontmatter fields and the exact section order every endpoint spec must follow:Required frontmatter: resource, protocol: http, method, path (:param for path params), version: 1.Section order: ## Request → ## Expected response → ## Error responses (optional, reference only) → ## Assertions (optional) → ## Tests (optional) → ## Notes (optional).The agent uses this to generate a complete, valid spec without guessing at structure.

Variable syntax

Variables in ## Request and ## Expected response http blocks use double-brace syntax: {{name}}. The skill explains the resolution chain:

_shared/env.md under the matching [<env>] section
.env.local in the project root (for secrets)
MAD_* environment variables

Secrets must never appear in markdown files — the agent learns to reference {{authToken}} and expect the value to come from .env.local or the environment.

Assertion operators

The skill lists every assertion operator the agent can add to a ## Assertions section:

Operator	Example
Exact status match	`status: 200`
Field existence	`body.id: exists`
Enum membership	`body.role: in [admin, user]`
Substring match	`headers.content-type: contains json`
Regex match	`body.slug: matches ^[a-z]+$`

The agent uses these to add meaningful assertions rather than leaving the section empty.

Pipeline capture patterns

The skill shows the capture expression syntax used to pass values between steps in a pipeline:

response.body.id — scalar field
response.body[0].id — first array element
response.body.data.token — nested field
response.headers.Location — response header

The agent uses capture expressions when building flows/ pipelines that chain endpoint calls together.

When to use MCP tools vs. shell commands

The skill includes a decision table so the agent picks the right tool for each task:

Situation	Use
Execute a single endpoint spec	`mad_exec` MCP tool
Run a multi-step pipeline	`mad_flow` MCP tool
Create or update a spec file	`mad_author` MCP tool
Search specs by method, path, or tag	`mad_search` MCP tool
Show variable resolution for a spec	`mad_vars` MCP tool
Execute multiple specs in one call	`mad_exec_batch` MCP tool
Validate a spec or directory	`mad validate` shell command
Rebuild the index	`mad index` shell command
Debug a failing endpoint	`/mad-debug` slash command

The agent never invokes mad_exec to create files, and never writes spec files directly without going through mad_author.

Rules the agent must follow

The skill ends with a short, firm rules section the agent treats as constraints:

Use mad_author, not direct file writes, for all spec creation and updates.
Run mad index after writing or updating any spec.
Default to --env=dev. Confirm explicitly before using --env=prod.
Never embed secrets in markdown — use .env.local or MAD_* environment variables.
Use realistic field names and values in specs — never "string" or 1 as placeholder content.

How agents use the skill in practice

When you ask your agent to document an endpoint — for example, “document POST /orders” — it follows a sequence driven by what it learned from the skill:

Read the skill

The agent loads .claude/skills/mad/SKILL.md (or the equivalent for your agent) and internalizes the spec format, project layout, and rules.

Locate the handler

The agent searches the source code for the POST /orders route handler and reads the request body type, response shape, and any authentication requirements.

Author the spec

The agent calls mad_author with a fully-formed spec: correct frontmatter, a realistic ## Request block with real field values, an ## Expected response block matching the handler’s return type, and ## Assertions covering at least the status code and one body field.

Validate and index

After mad_author writes the file (it validates before writing), the agent runs mad index to regenerate api-docs/README.md.

The agent does all of this autonomously because the skill told it exactly what to do at each step.

Keep skills up to date

Re-run the install command at any time to overwrite existing skill files with the version bundled in the current CLI release:

mad install skills

For a specific agent only:

mad install skills --agent=claude-code

Run mad install list to check whether your installed skill files match the current CLI version before deciding whether to reinstall. The output shows a ✓ or ✗ next to each agent’s skill status so you can see at a glance which ones need refreshing.

Documentation Index

​What a skill is

​Where skills are installed

​What the mad skill covers

​How agents use the skill in practice

​Keep skills up to date

What a skill is

Where skills are installed

What the mad skill covers

How agents use the skill in practice

Keep skills up to date