| name | generate-mintlify-reference |
| license | MIT |
| description | Generates drift-checked CLI, MCP, or API reference documentation for a Mintlify site from authoritative sources and wires regeneration checks. Use when adding or repairing source-backed Mintlify reference pages; do not use for hand-authored guides, source-code docstrings, or non-documentation code generation. |
Generate Mintlify reference documentation
Set up generated, drift-checked reference pages for a Mintlify site. The
governing principle is that reference pages are never hand-edited. A generator
reads the source of truth (the CLI's help, the live MCP instance, or the OpenAPI
specification) and emits MDX; CI regenerates and fails on drift, so the reference
cannot go stale.
When the official mintlify capability is available, use it for current
<ParamField>, <Tabs>, and docs.json syntax. Otherwise inspect the site's
existing components and current Mintlify documentation instead of guessing.
The patterns this skill enforces are in
references/reference-patterns.md.
Pick a target
Use the requested target from the user's prompt, including any text supplied
after an explicit skill invocation. The target is one of cli, mcp, api.
- cli — generate
reference/cli.mdx (and per-domain reference/cli/*.mdx)
from the CLI's own help/introspection. Template:
scripts/gen_cli_reference.py.
- mcp — generate
reference/mcp-tools.mdx (and per-domain
reference/mcp-tools/*.mdx) by introspecting the live MCP server. Template:
scripts/gen_mcp_reference.py.
- api — generate endpoint pages from an OpenAPI/AsyncAPI spec. This is the
one case Mintlify already automates well: prefer Mintlify's native OpenAPI
navigation over a custom generator. Use the available Mintlify capability or
current official documentation for the
docs.json openapi wiring; this
skill only adds the house framing (overview landing page, the "From Claude"
nudge, description/icon).
Instructions
Step 1: Find the source of truth
- CLI: locate the entry point (a
console_scripts in pyproject.toml, a
bin in package.json, or the main/argparse/click/typer module).
- MCP: locate the server module that registers tools (e.g. a FastMCP instance).
- API: locate the OpenAPI spec (
openapi.json/openapi.yaml) or the generator
that emits it.
Step 2: Adapt the generator template
Copy the matching template from scripts/ into the product repo's
scripts/ directory and adapt the marked ADAPT points (import paths, output
path, header text). The generator must:
- Emit a
{/* GENERATED by scripts/<name> — do not edit by hand. */} banner.
- Write deterministic output (sort tools/commands; collapse whitespace) so drift
CI is stable across machines.
- Use
<ParamField> or parameter tables per
references/reference-patterns.md.
Step 3: Wire the Makefile and CI
Add a docs-reference make target that runs the generators, and a CI job ("Docs
Reference Freshness") that regenerates and fails on drift. The CI snippet is in
references/reference-patterns.md.
Step 4: Split by domain when it grows
Once a reference has more than a handful of commands/tools, split it into
per-domain pages with an overview landing, and
add the group to docs.json Reference tab. Keep the generator emitting one file
per domain.
Step 5: Regenerate and link-check
Run make docs-reference (or the generators directly), then mint validate and
mint broken-links --check-anchors --check-redirects. Run the generator again
and verify the committed output remains unchanged.
Scope
This skill produces generators and the reference MDX they emit, plus the drift CI
wiring. It does not write hand-authored guides or concepts pages (use
review-mintlify-docs) and does not touch the changelog (use
write-mintlify-changelog).
