mintlify - SKILL.md Agent Skill

name: mintlify description: Rules for Mintlify documentation

Mintlify technical writing rule

You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.

Core writing principles

Language and style requirements

Use clear, direct language appropriate for technical audiences
Write in second person ("you") for instructions and procedures
Use active voice over passive voice
Employ present tense for current states, future tense for outcomes
Avoid jargon unless necessary and define terms when first used
Maintain consistent terminology throughout all documentation
Keep sentences concise while providing necessary context
Use parallel structure in lists, headings, and procedures

Content organization standards

Lead with the most important information (inverted pyramid structure)
Use progressive disclosure: basic concepts before advanced ones
Break complex procedures into numbered steps
Include prerequisites and context before instructions
Provide expected outcomes for each major step
Use descriptive, keyword-rich headings for navigation and SEO
Group related information logically with clear section breaks

User-centered approach

Focus on user goals and outcomes rather than system features
Anticipate common questions and address them proactively
Include troubleshooting for likely failure points
Write for scannability with clear headings, lists, and white space
Include verification steps to confirm success

Mintlify component reference

Callout components

Note - Additional helpful information

Supplementary information that supports the main content without interrupting flow

Tip - Best practices and pro tips

Expert advice, shortcuts, or best practices that enhance user success

Warning - Important cautions

Critical information about potential issues, breaking changes, or destructive actions

Info - Neutral contextual information

Background information, context, or neutral announcements

Check - Success confirmations

Positive confirmations, successful completions, or achievement indicators

Code components

Single code block

Example of a single code block:

const apiConfig = {
  baseURL: 'https://api.example.com',
  timeout: 5000,
  headers: {
    'Authorization': `Bearer ${process.env.API_TOKEN}`
  }
};

Code group with multiple languages

Example of a code group:

```javascript Node.js const response = await fetch('/api/endpoint', { headers: { Authorization: `Bearer ${apiKey}` } }); ```

import requests
response = requests.get('/api/endpoint', 
  headers={'Authorization': f'Bearer {api_key}'})

curl -X GET '/api/endpoint' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Request/response examples

Example of request/response documentation:

```bash cURL curl -X POST 'https://api.example.com/users' \ -H 'Content-Type: application/json' \ -d '{"name": "John Doe", "email": "john@example.com"}' ``` ```json Success { "id": "user_123", "name": "John Doe", "email": "john@example.com", "created_at": "2024-01-15T10:30:00Z" } ```

Structural components

Steps for procedures

Example of step-by-step instructions:

Run `npm install` to install required packages. Verify installation by running `npm list`. Create a `.env` file with your API credentials.

API_KEY=your_api_key_here

Never commit API keys to version control.

Tabs for alternative content

Example of tabbed content:

```bash brew install node npm install -g package-name ``` ```powershell choco install nodejs npm install -g package-name ``` ```bash sudo apt install nodejs npm npm install -g package-name ```

Accordions for collapsible content

Example of accordion groups:

- **Firewall blocking**: Ensure ports 80 and 443 are open - **Proxy configuration**: Set HTTP_PROXY environment variable - **DNS resolution**: Try using 8.8.8.8 as DNS server ```javascript const config = { performance: { cache: true, timeout: 30000 }, security: { encryption: 'AES-256' } }; ```

Cards and columns for emphasizing information

Example of cards and card groups:

Complete walkthrough from installation to your first API call in under 10 minutes. Learn how to authenticate requests using API keys or JWT tokens. Understand rate limits and best practices for high-volume usage.

API documentation components

Parameter fields

Example of parameter documentation:

Unique identifier for the user. Must be a valid UUID v4 format. User's email address. Must be valid and unique within the system. Maximum number of results to return. Range: 1-100. Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Response fields

Example of response field documentation:

Unique identifier assigned to the newly created user. ISO 8601 formatted timestamp of when the user was created. List of permission strings assigned to this user.

Expandable nested fields

Example of nested field documentation:

Complete user object with all associated data. User profile information including personal details. User's first name as entered during registration.

<ResponseField name="avatar_url" type="string | null">
URL to user's profile picture. Returns null if no avatar is set.
</ResponseField>

Media and advanced components

Frames for images

Wrap all images in frames:

Main dashboard showing analytics overview

Videos

Use the HTML video element for self-hosted video content:

<video controls className="w-full aspect-video rounded-xl" src="link-to-your-video.com"

Embed YouTube videos using iframe elements:

Tooltips

Example of tooltip usage:

API

Updates

Use updates for changelogs:

## New features - Added bulk user import functionality - Improved error messages with actionable suggestions

Bug fixes

Fixed pagination issue with large datasets
Resolved authentication timeout problems

Required page structure

Every documentation page must begin with YAML frontmatter:

---
title: "Clear, specific, keyword-rich title"
description: "Concise description explaining page purpose and value"
---

Content quality standards

Code examples requirements

Always include complete, runnable examples that users can copy and execute
Show proper error handling and edge case management
Use realistic data instead of placeholder values
Include expected outputs and results for verification
Test all code examples thoroughly before publishing
Specify language and include filename when relevant
Add explanatory comments for complex logic
Never include real API keys or secrets in code examples

API documentation requirements

Document all parameters including optional ones with clear descriptions
Show both success and error response examples with realistic data
Include rate limiting information with specific limits
Provide authentication examples showing proper format
Explain all HTTP status codes and error handling
Cover complete request/response cycles

Accessibility requirements

Include descriptive alt text for all images and diagrams
Use specific, actionable link text instead of "click here"
Ensure proper heading hierarchy starting with H2
Provide keyboard navigation considerations
Use sufficient color contrast in examples and visuals
Structure content for easy scanning with headers and lists

Component selection logic

Use Steps for procedures and sequential instructions
Use Tabs for platform-specific content or alternative approaches
Use CodeGroup when showing the same concept in multiple programming languages
Use Accordions for progressive disclosure of information
Use RequestExample/ResponseExample specifically for API endpoint documentation
Use ParamField for API parameters, ResponseField for API responses
Use Expandable for nested object properties or hierarchical information