Mintlify
Configure Mintlify API reference pages from OpenAPI, AsyncAPI, and MDX when shipping developer-facing docs for your product.
Overview
Mintlify is an agent skill for the Build phase that configures API reference docs using OpenAPI, AsyncAPI, and MDX in Mintlify’s `docs.json` model.
Install
npx skills add https://github.com/codewithshreyans/skills --skill mintlifyWhat is this skill?
- Wire single or multiple OpenAPI files through `docs.json` `api.openapi` entries
- Navigation groups can reference concrete operations like `GET /users` and `POST /users`
- OpenAPI extensions: `x-hidden`, `x-excluded`, and `x-codeSamples` for tailored examples
- MDX frontmatter `api: POST /path` for endpoints without a full spec
- AsyncAPI channel pages via `asyncapi` frontmatter for WebSocket and event APIs
Adoption & trust: 1.3k installs on skills.sh; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have OpenAPI or AsyncAPI files but keep misconfiguring Mintlify navigation, hidden endpoints, or manual MDX API pages.
Who is it for?
Indie API founders documenting v1 endpoints in Mintlify alongside a existing spec in the repo.
Skip if: Teams on unrelated doc platforms, pure prose guides with no API surface, or marketing landing copy without reference pages.
When should I use this skill?
When configuring Mintlify API docs, OpenAPI/AsyncAPI wiring, navigation endpoint lists, or MDX manual API pages.
What do I get? / Deliverables
Your agent produces correct `docs.json` and frontmatter patterns so API and event channels appear in nav with playgrounds and samples as intended.
- Updated `docs.json` API section
- Navigation groups referencing operations or channels
- MDX API pages with correct frontmatter
Recommended Skills
Journey fit
Build/docs is the natural home for wiring `docs.json`, OpenAPI specs, and manual MDX API pages before launch. Docs subphase covers structured API publishing—not runtime backend code or distribution campaigns.
How it compares
Mintlify-specific docs.json recipes—not a generic OpenAPI linter or full technical writing skill.
Common Questions / FAQ
Who is mintlify for?
Solo builders and small teams publishing Mintlify developer docs who want agents to edit specs, nav, and MDX API pages correctly.
When should I use mintlify?
Use it during Build/docs when wiring OpenAPI to navigation, adding AsyncAPI channels, configuring playgrounds, or authoring MDX pages for undocumented endpoints.
Is mintlify safe to install?
The skill is documentation guidance only; review the Security Audits panel on this Prism page and treat generated config like any other repo change.
SKILL.md
READMESKILL.md - Mintlify
# API documentation reference Setting up API documentation with OpenAPI, AsyncAPI, and MDX manual pages. ## OpenAPI setup Add your OpenAPI spec to `docs.json`: ```json "api": { "openapi": "openapi.json" } ``` Multiple specs: ```json "api": { "openapi": ["openapi/v1.json", "openapi/v2.json"] } ``` Reference individual endpoints in navigation: ```json { "group": "Users", "openapi": "openapi.json", "pages": ["GET /users", "POST /users", "GET /users/{id}"] } ``` ## OpenAPI extensions - `x-hidden`: Creates page but hides from navigation. - `x-excluded`: Completely excludes endpoint from docs. - `x-codeSamples`: Custom code examples per endpoint. ```yaml paths: /users: get: x-codeSamples: - lang: "bash" label: "List users" source: | curl https://api.example.com/users ``` ## MDX manual API pages For endpoints without an OpenAPI spec: ```yaml --- title: "Create user" api: "POST https://api.example.com/users" --- ``` Or with a base URL configured in `docs.json`: ```yaml --- title: "Create user" api: "POST /users" --- ``` ## AsyncAPI For WebSocket and event-driven APIs: ```json "api": { "asyncapi": "asyncapi.yaml" } ``` Reference channels in frontmatter: ```yaml --- title: "WebSocket channel" asyncapi: "/path/to/asyncapi.json channelName" --- ``` ## Playground configuration Control the API playground behavior in `docs.json`: ```json "api": { "playground": { "display": "interactive", "proxy": true }, "examples": { "languages": ["bash", "javascript", "python"], "defaults": "all", "prefill": false, "autogenerate": true }, "mdx": { "server": "https://api.example.com", "auth": { "method": "bearer" } } } ``` - `playground.display`: `"interactive"`, `"simple"`, or `"none"`. - `examples.languages`: `bash`, `go`, `java`, `javascript`, `node`, `php`, `powershell`, `python`, `ruby`, `swift`. - `examples.defaults`: `"required"` or `"all"` (include optional params). - `mdx.auth.method`: `"bearer"`, `"basic"`, `"key"`, `"cobo"`. # Components reference Full syntax and props for all Mintlify components. ## Callouts Styled alert boxes for important information. ```mdx <Note>Supplementary information, safe to skip.</Note> <Info>Helpful context such as permissions or prerequisites.</Info> <Tip>Recommendations or best practices.</Tip> <Warning>Potentially destructive actions or important caveats.</Warning> <Check>Success confirmation or completed status.</Check> <Danger>Critical warnings about data loss or breaking changes.</Danger> ``` Custom callout with icon and color: ```mdx <Callout icon="key" color="#FFC107" iconType="regular"> Custom callout with specific icon and color. </Callout> ``` ## Accordions Expandable/collapsible content sections. ```mdx <Accordion title="Click to expand" icon="star" defaultOpen={false}> Hidden content revealed on click. </Accordion> ``` Group multiple accordions: ```mdx <AccordionGroup> <Accordion title="First section">Content one.</Accordion> <Accordion title="Second section">Content two.</Accordion> </AccordionGroup> ``` Props: - `title` (string, required): Header text. - `description` (string): Detail text below title. - `defaultOpen` (boolean, default: false): Initially expanded. - `icon` (string): Icon name. - `iconType` (string): Font Awesome style. ## Cards Visual containers with titles, icons, and optional links. ```mdx <Card title="Card title" icon="rocket" href="/quickstart"> Card description text. </Card> ``` ```mdx <Card title="With image" img="/images/example.png" href="/guide" cta="Read guide" horizontal > Card with image and custom CTA. </Card> ``` Props: - `title` (string, required): Card title. - `icon` (string): Icon name. - `iconType` (string): Font Awesome style. - `color` (string): Hex color for icon. - `href` (string): Link destination. - `horizontal` (boolean): Compact horizontal layout. - `img` (string): Image URL or p