Skip to main content
hc
Submit
skillsFirst-partyReview first Safety · Privacy ·

Mintlify AI Documentation Automation Skill

Automate beautiful, searchable documentation creation with Mintlify - the modern AI-native documentation platform.

by JSONbored·added 2025-10-16·
Claude CodeCodexWindsurfGeminiCursorCLI
HarnessClaude CodeCodexWindsurfGeminiCursorCLI
Level:advancedType:generalVerified:draft
Review first — review before installing

Open the source and read safety notes before installing.

Prerequisites

  • Node.js 18+
  • Mintlify CLI: npm install -g mintlify
  • Codebase with JSDoc or TypeScript types
  • OpenAPI specification (optional, for API reference)
  • Mintlify account and API access (free tier available) for documentation site hosting and deployment
  • File system read/write access for Mintlify configuration files (mint.json), documentation source files, and generated documentation outputs

Schema details

Install type
package
Reading time
6 min
Difficulty score
100
Troubleshooting
Yes
Breaking changes
No
Package metadata
Package verified
Yes
SHA-256
23f581d57c2ddb576db5b593baf9f02b5de5314dda4042592ee3ed366bdc27c9
Skill and platform metadata
Skill type
general
Skill level
advanced
Verification
draft
Verified at
2025-10-16
Retrieval sources
https://mintlify.com/docs
Tested platforms
ClaudeCodexOpenClawCursorWindsurfGemini
PlatformSupportInstall path
claude-codeNative.claude/skills/<skill-name>/SKILL.md
codexNative.agents/skills/<skill-name>/SKILL.md
windsurfNative.windsurf/skills/<skill-name>/SKILL.md
geminiNative.gemini/skills/<skill-name>/SKILL.md or .agents/skills/<skill-name>/SKILL.md
cursorAdapter.cursor/rules/<skill-name>.mdc
cliManualAGENTS.md or tool-specific context file
Full copyable content
---
title: Get User
description: Retrieve a user by their unique identifier
api: GET /api/users/{userId}
---

# Get User

Retrieves a user by their unique identifier.

## Path Parameters

<ParamField path="userId" type="string" required>
  The user's unique identifier
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  Unique user identifier
</ResponseField>

<ResponseField name="email" type="string" required>
  User's email address
</ResponseField>

## Code Examples

<CodeGroup>

```typescript TypeScript SDK
import { getUser } from '@yourapp/sdk';
const user = await getUser('user_123');
```

```python Python
import requests
response = requests.get('https://api.yourapp.com/users/user_123')
```

</CodeGroup>

About this resource

What This Skill Enables

Claude can generate comprehensive, production-ready documentation using Mintlify - the modern documentation platform that has become the standard for developer-facing docs in 2025. This skill enables automatic API reference generation from code, interactive MDX components, multi-version documentation, and AI-powered content creation from JSDoc/TypeScript types.

Compatibility

Native

  • Claude Code / Claude: native skill usage via SKILL.md.
  • Codex/OpenAI workflows: compatible with Agent Skills-style SKILL.md content as reusable workflow instructions.

Manual Adaptation

  • Gemini CLI: native skill usage via .gemini/skills/<skill-name>/SKILL.md or .agents/skills/<skill-name>/SKILL.md where supported.
  • Cursor: use the generated .cursor/rules/*.mdc adapter for project rules.
  • OpenClaw and similar agents: use the same skill content as a reusable prompt/workflow file when native skill import is unavailable.

Prerequisites

Required:

  • Node.js 18+
  • Existing codebase with functions/APIs to document
  • Basic understanding of Markdown

What Claude handles automatically:

  • Generating MDX documentation from TypeScript/JSDoc
  • Creating mint.json configuration with navigation
  • Building API reference pages from OpenAPI specs
  • Setting up interactive code examples
  • Configuring search, analytics, and versioning
  • Creating custom MDX components

How to Use This Skill

API Documentation from TypeScript

Prompt: "Generate Mintlify documentation from my TypeScript API client at src/api/users.ts. Include all JSDoc comments, parameter types, return types, and code examples."

Claude will:

  1. Parse TypeScript file and extract exported functions
  2. Read JSDoc comments for descriptions
  3. Generate MDX files for each API endpoint
  4. Create proper Mintlify components (ParamField, ResponseField)
  5. Add code examples in multiple languages
  6. Generate response examples with proper formatting
  7. Update mint.json navigation

OpenAPI to Interactive Documentation

Prompt: "Convert my OpenAPI 3.0 spec (openapi.yaml) into Mintlify documentation with interactive API playground and authentication examples."

Claude will create:

  1. API reference section in mint.json
  2. MDX file for each endpoint with proper structure
  3. Request/response examples using CodeGroup
  4. Authentication documentation with examples
  5. Error code reference table
  6. API playground integration
  7. SDK code examples (TypeScript, Python, cURL)

Complete Documentation Site Setup

Prompt: "Set up a complete Mintlify documentation site for my SaaS product with: Introduction, Quickstart, API Reference, Guides, Changelog. Include dark mode, search, and analytics."

Claude will generate:

  1. Directory structure with organized MDX files
  2. mint.json with proper navigation tabs
  3. Introduction page with hero and feature cards
  4. Quickstart with step-by-step instructions
  5. API reference structure
  6. Guide templates
  7. Changelog format
  8. Dark mode configuration
  9. Search and analytics integration

Interactive Component Library Documentation

Prompt: "Document my React component library with interactive examples, prop tables, and usage guidelines. Components are in src/components/ui."

Claude will create:

  1. Component documentation pages with descriptions
  2. PropTable components with TypeScript types
  3. Interactive code playgrounds
  4. Usage examples with best practices
  5. Accessibility guidelines per component
  6. Storybook integration links
  7. Installation and import instructions

Tips for Best Results

  1. Rich JSDoc Comments: Ensure your code has comprehensive JSDoc comments with @param, @returns, @throws, and @example tags for best auto-generation results.

  2. OpenAPI First: If you have an OpenAPI spec, use that as the source of truth. Mintlify's OpenAPI integration is more reliable than manual documentation.

  3. Code Examples: Request examples in multiple languages (TypeScript, JavaScript, Python, cURL) to maximize usefulness for different audiences.

  4. Interactive Elements: Ask for Mintlify-specific components (Accordion, Card, Tabs, CodeGroup) to make docs more engaging than plain Markdown.

  5. Version Management: For libraries, request versioned documentation setup from the start to avoid migration pain later.

  6. Search Optimization: Include descriptive meta titles and descriptions in frontmatter for better search discoverability.

Common Workflows

Complete API Documentation

"Generate full Mintlify API documentation:
1. Parse src/api/*.ts files for all exported functions
2. Create API reference pages with proper Mintlify components
3. Include TypeScript type definitions
4. Add code examples in TypeScript, JavaScript, Python, and cURL
5. Document all error codes and responses
6. Set up authentication guide with OAuth 2.0 flow
7. Configure API playground with authentication
8. Add rate limiting documentation"

Component Library Docs

"Build Mintlify docs for React component library:
1. Document all components in src/components/ui
2. Extract prop types from TypeScript interfaces
3. Create PropTable for each component
4. Add usage examples with CodeGroup
5. Include accessibility guidelines (ARIA, keyboard)
6. Link to Storybook for interactive demos
7. Add installation guide with package manager options
8. Create theming and customization guide"

SDK Documentation with Examples

"Generate SDK documentation from TypeScript client:
1. Document all SDK methods with parameters and returns
2. Create quickstart with installation and auth setup
3. Add comprehensive code examples for each method
4. Include error handling patterns
5. Document webhook integration
6. Add retry and timeout configuration
7. Create migration guide from v1 to v2
8. Set up changelog with semantic versioning"

Multi-Version Documentation

"Set up versioned Mintlify docs for API v1 and v2:
1. Create separate documentation for each version
2. Configure version switcher in mint.json
3. Highlight breaking changes between versions
4. Provide migration guide from v1 to v2
5. Maintain v1 docs in archive with deprecation notice
6. Set up URL structure: /v1/... and /v2/...
7. Add version-specific examples"

Troubleshooting

Issue: Mintlify build fails with "Invalid frontmatter" Solution: Ensure all MDX files have valid YAML frontmatter with required fields (title, description). Ask Claude to validate frontmatter syntax.

Issue: Navigation doesn't match folder structure Solution: mint.json navigation must explicitly list all pages. Ask Claude to regenerate navigation section matching your actual MDX file structure.

Issue: Code examples aren't syntax highlighted correctly Solution: Specify language in code fence (typescript, not ts). Ask Claude to use full language names for better highlighting.

Issue: API Reference pages look inconsistent Solution: Use Mintlify's built-in components (ParamField, ResponseField) instead of manual tables. Request Claude to refactor using proper components.

Issue: Search doesn't find relevant pages Solution: Add descriptive seoTitle and description in frontmatter. Ask Claude to optimize metadata for search.

Learn More

Features

  • Auto-generate docs from TypeScript/JSDoc with parameter and return type extraction
  • OpenAPI to interactive API reference with authentication and playground
  • Interactive MDX components (Tabs, Accordion, CodeGroup, Steps, Cards, ParamField, ResponseField)
  • Multi-version documentation support with version switcher
  • Built-in search and analytics integration (PostHog, Google Analytics)
  • API playground with authentication and code examples in multiple languages
  • Dark mode support with customizable themes and branding
  • Automated deployment with Vercel integration and CI/CD workflows

Use Cases

  • API reference documentation from code with interactive playground
  • SDK and library documentation with installation guides and examples
  • Product documentation with guides, tutorials, and quickstarts
  • Component library documentation with prop tables and interactive examples
  • Multi-version API documentation with migration guides
  • Internal knowledge base with search and analytics
Content outline
#mintlify#documentation#mdx#api-docs#automation

Source citations

Signals

Loading live community signals…

More like this, weekly

A short, calm digest of reviewed Claude resources. Unsubscribe any time.