Write and edit Mintlify documentation with Windsurf

Use Windsurf’s Cascade and Tab AI features to draft, edit, and maintain your Mintlify documentation with full awareness of components and writing standards.

Windsurf’s AI features work best for documentation when they understand Mintlify’s component library, frontmatter conventions, and writing standards. Installing the Mintlify skill gives Windsurf that context, so Cascade conversations and Tab completions follow the patterns your docs site expects.

Prerequisites

• Windsurf installed on your machine
• A Mintlify docs repository with a docs.json file at the root

Setup

1. Open your docs directory in Windsurf

   Open the folder that contains your docs.json file as the project root in Windsurf. Windsurf’s AI features use the open project for context, so opening the correct directory ensures the skill is applied to the right files.

2. Install the Mintlify skill

   In Windsurf’s integrated terminal, run the following command from your docs root:

   npx skills add https://mintlify.com/docs
   

   This installs Mintlify’s component reference, writing standards, and workflow guidance into Windsurf’s context. After installation, Windsurf’s AI features will understand how to use <Steps>, <Card>, <Tabs>, and all other Mintlify components correctly.

3. Customize AGENTS.md

   Open the AGENTS.md file created in your docs root and add any project-specific instructions. This file defines the rules that apply to your docs site in particular, such as product terminology, style preferences, and content scope.

   ## Terminology
   - Use "workspace" not "project"
   - Use "deployment" not "publish"
   
   ## Style
   - Keep code examples under 20 lines
   - Always include a description callout before API reference tables
   

   AGENTS.md is the right place to capture your product’s vocabulary, tone, and content boundaries. Windsurf reads this file alongside the installed skill, so your project-specific rules are applied consistently without needing to repeat them in every prompt.

4. Start writing

   Use Windsurf’s AI features to draft and edit documentation:

   • Cascade — Open the Cascade panel to ask Windsurf to draft a new page, restructure a section, or apply a specific Mintlify component
   • Tab — Accept inline completions as you type in .mdx files

   Windsurf will apply Mintlify component syntax, frontmatter conventions, and your AGENTS.md rules throughout the session.