Build and validate Mintlify documentation with ak:mintlify

Use ak:mintlify to build or maintain a Mintlify documentation project. The Skill covers docs.json, MDX pages and components, navigation, OpenAPI and AsyncAPI references, AI-facing documentation assets, local validation, and deployment patterns while keeping repository edits separate from hosted account changes.

Choose ak:mintlify for Mintlify projects

Use ak:mintlify when

• You need to scaffold or restructure a Mintlify docs project.
• You need to update docs.json, navigation, branding, theme, redirects, search, API configuration, or integrations.
• You need Mintlify MDX pages with frontmatter, content components, API fields, request or response examples, cards, tabs, steps, or Mermaid blocks.
• You need to connect reviewed OpenAPI or AsyncAPI source to reference pages.
• You need local checks, a preview, CI validation, AI-facing assets, or a deployment plan for an existing Mintlify site.

Choose another workflow when

• The repository uses Fumadocs, Docusaurus, MkDocs, Sphinx, or another platform. Use its native conventions rather than converting the project implicitly.
• You only need concise factual prose independent of a docs platform. Use ak:docs.
• You only need a general deployment workflow. Use ak:deploy after the Mintlify project is valid and the hosting target is approved.
• You need to operate the Mintlify dashboard, DNS provider, Git host, analytics account, Slack, Discord, or another external service without an authorized session.

Prepare the project and platform boundary

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the current runtime and scope.
• Provide the docs root, existing docs.json or legacy configuration, package manager, repository instructions, target audience, information architecture, brand assets, supported locales or versions, and allowed file boundary.
• Identify the installed Mintlify CLI version. The pinned Skill uses mint commands, but platform schemas, components, themes, integrations, and hosting behavior can change; verify the active version before relying on a reference example.
• Supply authoritative API specifications, endpoint behavior, examples, authentication rules, and error contracts. Remove real credentials and production tokens.
• Separate local authorization from hosted authorization: file edits and local preview do not grant permission to connect Git, create previews, change DNS, enable analytics, expose an API playground, or deploy.

The declared input is [task] [path]. Give the exact project path, desired outcome, files that may change, validation commands, network policy, and whether the run must stop before preview, account configuration, or deployment.

Request a bounded documentation change

/ak:mintlify "In ./docs-site, add an Authentication group using the existing docs.json structure and write overview.mdx from the approved OpenAPI spec. Preserve current branding and navigation order, use placeholder credentials only, run mint validate, mint broken-links, and mint openapi-check with the installed CLI, and stop before mint dev, Git changes, dashboard configuration, or deployment."

/ak:mintlify "In ./docs-site, add an Authentication group using the existing docs.json structure and write overview.mdx from the approved OpenAPI spec. Preserve current branding and navigation order, use placeholder credentials only, run mint validate, mint broken-links, and mint openapi-check with the installed CLI, and stop before mint dev, Git changes, dashboard configuration, or deployment."

$ak:mintlify "In ./docs-site, add an Authentication group using the existing docs.json structure and write overview.mdx from the approved OpenAPI spec. Preserve current branding and navigation order, use placeholder credentials only, run mint validate, mint broken-links, and mint openapi-check with the installed CLI, and stop before mint dev, Git changes, dashboard configuration, or deployment."

A good request states whether the project already exists, the required page tree, source-of-truth documents, public and private boundaries, supported devices and languages, expected link policy, accessibility bar, and which external systems must remain untouched.

Match the task to the affected surfaces

The reference library contains examples for many platform features. Do not infer that every example is enabled for the user's plan, CLI version, theme, region, or hosting model. Confirm support with the installed CLI and the target account before changing public behavior.

Use the pinned CLI commands deliberately

The Skill declares these local commands:

mint new
mint dev
mint validate
mint broken-links
mint a11y
mint openapi-check
mint rename <old> <new>
mint migrate-mdx
mint update

Run mint --help and the relevant subcommand help for the installed version before mutation. mint new scaffolds files, mint rename changes a file and references, mint migrate-mdx migrates legacy configuration, and mint update changes packages. Review their planned effects and preserve a diff or backup.

mint dev starts a local preview, documented by the pinned Skill on port 3000. It opens a listening process and may load remote fonts, assets, APIs, analytics, frames, or integrations referenced by the project. Use a reviewed environment, record the actual host and port, and stop the server after inspection.

Observe the documentation stages

1. The Skill inventories the project. It reads repository instructions, configuration, page tree, assets, specifications, package state, and existing conventions before proposing edits.
2. It confirms the information architecture. Audience, product, version, locale, navigation depth, routes, source ownership, and non-goals become an explicit contract.
3. It checks the active platform surface. CLI help and target configuration determine which pinned-reference fields and commands remain valid.
4. It applies the smallest file change. Configuration, navigation, content, specification mapping, and assets remain consistent rather than being rewritten as an unrelated template.
5. It validates locally. Configuration, links, accessibility, and API specs are checked with the relevant available commands; failures remain visible.
6. It previews when authorized. Required pages, navigation states, themes, viewports, components, code, API reference, search, and error paths are inspected in the actual rendered site.
7. It stops at the external gate. Git connection, provider dashboard, analytics, bots, domains, auth, preview publication, and deployment wait for explicit approval.
8. It returns evidence. The report names changed files, checks, preview findings, network calls, unsupported reference claims, and next approvals.

Keep secrets, interactive APIs, and hosted effects controlled

• Never place real API keys, tokens, passwords, webhook secrets, provider credentials, private endpoints, or customer data in docs.json, MDX, OpenAPI examples, playground prefill, generated AI assets, screenshots, or CI files. Use obvious placeholders and approved secret storage.
• An interactive playground can make live browser requests or route them through a proxy. Default it to a safe environment or disable it until authentication, CORS, rate limits, mutation behavior, and data retention are reviewed.
• Analytics, session replay, chat, marketing, and consent integrations affect privacy and may load third-party scripts. Require product, legal, and security approval appropriate to the deployment.
• Contextual actions can copy or send page content to AI tools, editors, or custom URLs. llms.txt, skill.md, MCP, search, bots, and AI indexing can increase the public machine-readable surface. Review inclusions and exclusions.
• Custom React components, iframes, custom CSS, redirects, reverse proxies, CSP, and authentication change the execution or trust boundary. Validate them as code and infrastructure.
• Connecting Git, publishing a preview, changing DNS or TLS, provisioning a domain, purging caches, or deploying to Mintlify, Vercel, Cloudflare, or AWS is an external state change. Local editing authority does not include it.

Verify outputs and evidence

A complete local result should include:

• Exact changed and generated files, including docs.json, MDX, API specs, assets, custom components, package metadata, CI configuration, and migration outputs in scope.
• The installed CLI version and results from mint validate, mint broken-links, mint a11y, and mint openapi-check when applicable, with unavailable or renamed commands reported rather than simulated.
• Route and navigation reconciliation: every configured page exists, ordering is intentional, product, version, locale, and tab contexts match, redirects resolve, and no expected page is orphaned.
• Factual reconciliation of prose, parameters, schemas, authentication, examples, responses, errors, and generated AI-facing content with approved sources.
• Preview evidence for required themes, viewport sizes, components, code blocks, images, Mermaid, API pages, search, links, 404 behavior, keyboard access, and contrast when a preview was authorized.
• A network and privacy inventory for playgrounds, proxies, frames, fonts, analytics, support widgets, AI tools, bots, MCP, Git, hosting, and domains.
• A clear statement that deployment did not occur, or separately authorized deployment evidence with target, URL, version, checks, and rollback.

The pinned stable and beta releases contain identical ak:mintlify files. The Skill contains reference Markdown only—no scripts, schemas, fixtures, or tests. Counts of themes, locales, components, listed integrations, command behavior, and hosted platform features are time-sensitive and must not be presented as current without verification.

Troubleshoot and interpret limits

Use ak:docs for platform-neutral prose, ak:deploy for an approved delivery workflow, or Runtime adapters to review session-specific tool boundaries.