document-reference

Document Reference

Set up generated, drift-checked reference pages for a Mintlify site. The governing principle (best-practices sections 2 and 4): reference pages are never hand-edited. A generator reads the source of truth (the CLI's help, the live MCP instance, the OpenAPI spec) and emits MDX; CI regenerates and fails on drift, so the reference cannot go stale.

For <ParamField>, <Tabs>, and other component syntax, defer to the official mintlify plugin. The patterns this skill enforces are in references/reference-patterns.md.

Pick a target

$ARGUMENTS 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 official mintlify plugin 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 (best-practices sections 3 and 10), 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 broken-links. Verify the committed output matches (no drift).

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 (that is review-docs) and does not touch the changelog (that is changelog-writer).