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.
Slash commands are markdown files that Claude Code and Codex CLI load as reusable agent workflows. MarkApiDown ships two: /mad for creating and enriching specs, and /mad-debug for diagnosing failures. You type the command in the agent chat, optionally pass an argument, and the agent follows a structured decision tree to completion — no manual prompting required.
Slash commands are only available in Claude Code and Codex CLI. If you use Cursor, GitHub Copilot, Antigravity, or OpenCode, use skills and MCP tools instead — they cover the same workflows through those agents’ native interfaces. Install slash commands
Run the following command from your project root to install both /mad and /mad-debug:
To install for a specific agent:
mad install slashcmd --agent=claude-code
mad install slashcmd --agent=codex-cli
| Agent | Install path |
|---|
| Claude Code | .claude/commands/mad.md and .claude/commands/mad-debug.md |
| Codex CLI | ~/.codex/commands/mad.md and ~/.codex/commands/mad-debug.md |
/mad — scan, enrich, and build flows
The /mad command routes to one of three modes depending on the argument you pass. You can invoke it by name, pass a target path, or describe a flow in plain language.
Scan mode
Enrich mode
Flow mode
Trigger: /mad, /mad scan, or /mad <directory>Scan mode imports or creates missing endpoint specs for your project. The agent runs mad import project first — if it finds an OpenAPI spec, it converts that. Otherwise, it reads your source routes directly and authors specs using mad_author.What the agent does:Auto-import
Runs mad import project <directory>. If MarkApiDown finds an OpenAPI spec, it converts it and skips to validation. If it generates stubs from a CLI export command (FastAPI, Spring Boot, etc.), it runs that first.
Read source routes
For any routes not covered by the import, the agent searches your source code for route definitions using patterns like @GetMapping, @app.get, router.get, and r.GET — adapting to your framework automatically.
Author specs
For each discovered route, the agent reads the handler and its type definitions, then calls mad_author with a complete spec: realistic request body, real field names, an expected response that matches the handler’s return type, and assertions covering the happy path and at least one error case.
Validate and index
Runs mad validate api-docs/ and then mad index to regenerate the index.
You: /mad scan src/routes/
Agent: Running mad import project src/routes/…
Found 3 unspecced routes: POST /orders, GET /orders/:id, DELETE /orders/:id
Authoring specs…
✓ api-docs/apis/orders/post-create-order.md
✓ api-docs/apis/orders/get-order-by-id.md
✓ api-docs/apis/orders/delete-order.md
Running mad validate api-docs/… all valid.
Running mad index… done.
Trigger: /mad enrich, /mad <file.md>, or /mad <directory> (when the target already has specs)Enrich mode fills in ## Expected response and ## Tests sections using live server responses. Use it after scan mode has created stubs, or whenever your API changes and you want to update existing specs.What the agent does:Read the spec and handler
Loads the spec file and the corresponding route handler to understand the intended response shape.
Execute with live response
Calls mad_exec with infer_expected: true if the server is running. Uses the actual HTTP response to populate ## Expected response with real field values — not stubs.
Add assertions
Writes a ## Assertions section with at minimum status: <code> and one body.<key>: exists check. Adds headers.content-type: contains json when appropriate.
Add tests
Writes a ## Tests section covering the happy path, an auth failure case, and one validation error case.
You: /mad enrich api-docs/apis/orders/post-create-order.md
Agent: Reading spec and POST /orders handler…
Executing against dev server…
HTTP 201 {"id": "ord_9f3b", "status": "pending", "total": 49.99}
Updating ## Expected response with real values…
Adding ## Assertions: status 201, body.id exists, body.status exists…
Adding ## Tests: happy path, 401 missing token, 422 missing items…
✓ Spec enriched.
Trigger: /mad flow or /mad <description of a multi-step scenario>Flow mode builds and runs a pipeline. Describe the scenario in plain language — the agent maps it to endpoint specs, works out the data dependencies, writes the pipeline file, validates it, and runs it.What the agent does:Map dependencies
Reasons about the data flow before writing anything. For example, a checkout flow requires a login step to capture authToken, then an order step to capture orderId, then a confirmation step that consumes both.
Write the pipeline
Authors api-docs/flows/<name>.md with steps in order, capture expressions, and inject references connecting each step to the previous one.
Validate and run
Runs mad validate api-docs/flows/<name>.md, then calls mad_flow to execute it. Reports per-step status, captured values (secrets masked as ****), assertion results, and the first failure with a diagnosis.
You: /mad flow checkout: login, create order, confirm payment
Agent: Planning data dependencies…
POST /auth/login → capture: authToken
POST /orders → inject: authToken → capture: orderId
POST /orders/:id/confirm → inject: authToken, orderId
Writing api-docs/flows/checkout.md…
Validating… valid.
Running flow…
Step 1 POST /auth/login ✓ 200 authToken captured
Step 2 POST /orders ✓ 201 orderId: ord_9f3b captured
Step 3 POST /orders/:id/confirm ✓ 200
Flow complete. All steps passed.
/mad-debug — diagnose failing specs
The /mad-debug command diagnoses a failing endpoint or pipeline. Pass it a spec file path, a pipeline file path, or a description of the endpoint that’s failing. The agent follows a structured diagnostic workflow and tells you exactly what to fix.
Trigger: /mad-debug <spec file> or /mad-debug <method> <path>The agent works through a fixed sequence of checks before drawing any conclusions.Locate the spec
Searches for the spec file using mad_search (via MCP) or rg on the api-docs/apis/ directory. If no spec exists for the failing endpoint, it tells you to run /mad first.
Validate
Runs mad validate <file>. If validation fails, the error output identifies the exact field or section to fix.
Dry run
Runs mad exec <file> --env=dev --dry-run and checks the resolved request: correct baseUrl, auth header present, path params substituted, body shape correct.
Execute
Calls mad_exec via MCP with the spec and any required variables. Captures the full response.
Interpret
Applies the following decision table to the result and tells you what to do:| Exit / result | Fix |
|---|
| Exit 2 — invalid spec | Fix frontmatter field or ## Request http block |
| Exit 4 — network error | Check baseUrl in _shared/env.md, confirm server is running |
| Exit 5 — secret detected | Move the value to .env.local or a MAD_* environment variable |
| Response mismatch | Update ## Expected response if the API changed; otherwise fix the API |
| 401 / 403 | Check authToken in env, verify auth: frontmatter matches the header |
| Unresolved variable | Check _shared/env.md for baseUrl, check .env.local for tokens |
You: /mad-debug api-docs/apis/orders/post-create-order.md
Agent: Validating spec… valid.
Dry run… baseUrl resolved to http://localhost:3000, auth header present.
Executing… HTTP 422 {"error": "items must not be empty"}
Exit 0, but assertion failed: status expected 201, got 422.
The request body is missing items. Check the ## Request block —
the example body is {} instead of {"items": [{"sku": "…", "qty": 1}]}.
Fix: update ## Request with a valid items array, then re-run.
Trigger: /mad-debug <pipeline file> or /mad-debug flow <name>Pipeline debugging focuses on finding the first failing step and diagnosing it as a single endpoint with the captured values from prior steps already injected.Locate and read
Lists files in api-docs/flows/ and reads the pipeline. Checks step order, capture expressions, inject names, and confirms all referenced spec files exist.
Execute the pipeline
Calls mad_flow via MCP and reads the per-step results.
Trace the failure
Identifies the first failing step and diagnoses it:
- Capture mismatch — the capture expression doesn’t match the real response shape. The agent shows you the actual response body and suggests the correct expression.
- Inject not resolved — a later step references a variable that wasn’t captured by an earlier step. The agent checks that the producing step succeeded and that the capture name matches the inject name exactly.
- Step failure — treats the failing step as a single endpoint and runs the full single-endpoint debug workflow above, injecting captured values from previous steps as
--var arguments.
You: /mad-debug api-docs/flows/checkout.md
Agent: Reading pipeline… 3 steps found.
Executing flow…
Step 1 POST /auth/login ✓ 200 authToken captured
Step 2 POST /orders ✗ 500 Internal Server Error
Tracing step 2 as single endpoint with authToken injected…
Executing mad_exec with vars: {authToken: "****"}…
HTTP 500 {"error": "Cannot read property 'id' of undefined"}
Exit 0, response status 500 — server-side error.
Check the POST /orders handler — it likely expects a userId that
isn't being passed. Add userId to the capture list in step 1
and inject it in step 2.
The /mad-debug command never prints raw auth tokens. It masks all secret values as **** in its output. Always run debug commands against --env=dev. The command will ask for explicit confirmation before running anything against --env=prod.
