mintlify__docs/assistant/skills.mdx

---
title: "Add assistant skills"
description: "Tune the assistant's responses with topic-specific Markdown guides that the assistant loads on demand to answer specific questions with your team's guidance."
keywords: ["assistant", "skills", "loadSkill", "guides", "system prompt"]
---

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/`:

```text 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:

```markdown .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.

<Note>
  After you add or change a `skill.md` file, redeploy your site to make the skill available to the assistant.
</Note>

## 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](/assistant/customize) 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](mailto:support@mintlify.com).