Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.markapidown.net/llms.txt

Use this file to discover all available pages before exploring further.

Vibe coding moves fast when every part of the loop — writing, running, reviewing — works together. MarkApiDown is the API layer in that loop: agents read and write markdown spec files, the CLI executes them, and the browser gives you a visual review surface while the agent works. Every change is a diff you can read in a pull request.

​
The four-step vibe coding loop

1

Ask your agent to document routes

Start by asking your agent to scan for API routes or document a specific endpoint. With the skill installed, the agent knows the MarkApiDown spec format and file layout without you explaining it.Example prompts:
“Scan this project for API routes and add missing MarkApiDown specs. Do not overwrite existing files.”
“Add a MarkApiDown spec for POST /orders. Use bearer auth. The request body should include customerId and items[].”
“Create a spec for the GET /users/:userId endpoint. Make userId a path param.”
The agent uses mad_author (via MCP) or writes the file directly, then runs mad validate to confirm the spec is structurally correct before moving on.
2

Review in the browser

Open the browser UI while your agent works — or after it finishes a batch of specs.
mad serve
In the browser you can:
  • Inspect the generated spec on the Request and Expected Response tabs.
  • Run the endpoint against your dev server using the runner panel.
  • Check the Diff tab to see whether the actual response matches the recorded expected response.
  • Edit the spec source directly in the Source tab if you spot something to fix.
The browser reads the same files the agent writes, so there is no sync step — changes appear immediately.
3

Build flows

Ask the agent to connect specs into a multi-step pipeline. Flows let you test sequences that depend on each other — for example, creating a user, logging in, capturing the token, and then calling a protected endpoint with it.
“Build a signup flow: create a user, then log in with those credentials, capture the token from the response, and fetch the user profile using the captured token.”
The agent writes a flow to api-docs/flows/signup.md that chains the steps together using capture and inject declarations. You can review the flow on the Flows canvas in the browser, run it visually step by step, and see captures fill in as each step completes.Run the flow from the CLI at any time:
mad flow api-docs/flows/signup.md --env=dev
4

Validate and commit

Before committing, run mad validate to confirm all spec files are structurally correct. Validation catches frontmatter errors, missing required sections, and any secrets that were accidentally written to a versioned file.
mad validate api-docs/
If validation passes, commit the api-docs/ directory. Every spec is a plain markdown file — reviewable in a pull request, diffable in GitHub, and readable by the next agent that works on the project.

​
Example agent prompts

Use these prompts as starting points. Adjust the endpoint details, field names, and environments to match your project.
GoalPrompt
Document one endpoint"Add a MarkApiDown spec for GET /users/:userId. Use bearer auth and make userId a path param."
Scan for missing specs"Scan this project for API routes and add missing MarkApiDown specs. Do not overwrite existing specs."
Run and debug"Test the get-user endpoint in dev. If variables are missing, tell me exactly where to define them."
Create a flow"Build a checkout flow: create an order, capture orderId from the response, then fetch the order using the captured orderId."
Enrich expected responses"Run the get-user endpoint and update its ## Expected response block with the actual field names and values from the response."
Validate before commit"Run mad validate api-docs/ and fix any errors before we commit."

​
Without MarkApiDown vs. with MarkApiDown

DimensionWithout MarkApiDownWith MarkApiDown
Token costAgent reads source files and re-discovers routes on every promptAgent reads compact spec index — one file describes the full collection
Debug experienceAgent parses raw curl output or builds requests from memoryAgent calls mad_exec and gets a structured diff with actionable hints
CI integrationManual — agent writes a test script that may not match the specAutomatic — mad validate and mad exec exit with stable codes CI can act on
Review experienceAPI changes are scattered across source files and commentsEvery API change is a .md diff in the pull request — readable and reviewable
Spec driftAgent re-generates boilerplate on every sessionSpecs persist in api-docs/ across sessions, agents, and contributors
Multi-step testingAgent chains curl calls manually, captures values by parsing textAgent writes a flow file; mad flow handles capture, inject, and reporting

​
The agent skill system

Skills are markdown playbooks embedded in the MarkApiDown binary. When you run mad install skills, MarkApiDown writes a SKILL.md file to each detected agent’s configuration directory — .claude/skills/ for Claude Code, .cursor/rules/ for Cursor, .github/instructions/ for Copilot, and so on. 
mad install skills

# Target one agent
mad install skills --agent=claude-code
mad install skills --agent=cursor
mad install skills --agent=copilot
Once installed, the skill activates automatically when API-related topics come up in the conversation. The agent does not need to be told about MarkApiDown explicitly — it recognizes the project layout, the spec format, and the correct CLI commands from the skill. The skill teaches agents:
  • The api-docs/ project layout and file naming convention.
  • The endpoint spec format: required frontmatter fields, section order, and variable syntax.
  • The assertions DSL and when to use ## Assertions vs ## Expected response.
  • The pipeline capture and inject syntax for flow files.
  • Which MCP tool to call for each operation, and when to fall back to CLI commands.
  • How to handle missing variables, auth errors, and contract mismatches.
Run mad doctor to check whether your installed skills are up to date with the current binary: 
mad doctor
If skills are stale, run mad install skills again to update them.

​
MCP tools available to agents

When you register the MCP server with Claude Code, the agent gets structured tools with compact JSON output. These tools are more reliable than asking the agent to parse terminal text. 
mad install mcp
# or equivalently:
claude mcp add mad -- mad mcp
ToolWhat it does
mad_execExecute one endpoint spec and return a structured diff result. Pass verbose: true for full request/response payloads, dry_run: true to resolve variables without sending.
mad_flowRun a pipeline and return per-step pass/fail state with captured values.
mad_validateValidate a spec file or directory and return a structured result with any parse errors.
mad_list_specsList all specs in the collection — method, path, title, and tags — without reading individual files.
mad_read_specRead the full content of one spec file, including frontmatter and all sections.
mad_authorCreate or update a spec file. Validates the content before writing; refuses to silently overwrite an existing file unless overwrite: true is set.
mad_searchSearch specs by method, path, tag, or text without reading individual files.
mad_varsShow which variables a spec requires and which are resolved for the current environment.
All tools return error_type and hint fields on failure so the agent can take the right action without parsing error messages.
Use the /mad and /mad-debug slash commands in Claude Code for tasks that benefit from LLM reasoning rather than structured tool calls. /mad handles spec creation, response enrichment, and flow building from natural-language descriptions. /mad-debug runs a multi-step diagnosis on a failing endpoint or pipeline and explains what went wrong in plain language.Install both with:
mad install slashcmd --agent=claude-code