Skip to main content
Skills are Markdown files that direct the assistant’s responses on specific topics. The assistant has access to any skills you add to your project in the .mintlify/assistant/skills/ directory. It loads a skill only when a user’s question matches it, so you can provide curated answers for specific topics without adding context to every response. Use skills to:
  • Provide specific answers for topics where search results alone are unreliable.
  • Encode playbooks, troubleshooting flows, or migration guides that aren’t structured as documentation pages.
  • Guide users through multi-step or nuanced procedures.

​
Add a skill

Add a skill.md file inside a directory named for the skill under .mintlify/assistant/skills/:
Example directory structure
.mintlify/
└── assistant/
    └── skills/
        ├── migrate-to-v3/
        │   └── skill.md
        └── debug-webhooks/
            └── skill.md
Each skill.md file needs YAML frontmatter with a name and description, followed by the skill instructions:
.mintlify/assistant/skills/migrate-to-v3/skill.md example skill file
---
name: Migrate to SDK v3
description: Step-by-step guide for upgrading from SDK v2 to v3, including breaking changes, code mods, and rollout checklist.
---

# Migrating to SDK v3

Follow these steps to upgrade an existing v2 integration to v3.

## 1. Update dependencies

...
The assistant uses the name and description to decide when to load a skill, so write descriptions that state when the skill applies. Keep the instructions concise. The assistant truncates skill content at approximately 6,000 tokens.
After you add or change a skill.md file, redeploy your site to make the skill available to the assistant.

​
How the assistant uses skills

The assistant lists every available skill by name, slug, and description in its system prompt. When a user’s question matches a skill description, the assistant loads the skill and treats it as high-priority guidance that takes precedence over general search results. The assistant can load up to three skills per response. On follow-up messages, the assistant removes previously loaded skill content from the conversation history to preserve the context window. It reloads a skill if it needs it again. Skills work alongside custom assistant instructions in .mintlify/Assistant.md. Use Assistant.md for tone, persona, and rules that apply to every response. Use skills for topic-specific guidance that the assistant should load only when relevant.

​
Write effective skills

  • Give each skill a distinct description. Overlapping descriptions make it harder for the assistant to load the right skill.
  • Use a unique, URL-safe slug for each directory name. Slugs must contain only lowercase letters, numbers, and hyphens. You cannot publish skills with duplicate slugs.
  • Structure skills with clear headings and numbered steps.
  • Keep skills self-contained. The assistant loads one skill at a time, so a skill should not depend on another skill.
  • Use prose and code samples. Do not use screenshots.

​
Disable skills

Skills are on by default when at least one skill.md file is present. To remove all skills, delete the .mintlify/assistant/skills/ directory and redeploy your site. To turn off the skills feature for your deployment, contact support.

Related topics

Create a knowledge baseskill.mdCustomize assistant behavior