generate-mintlify-reference

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