> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add assistant skills

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

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 theme={null}
.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 theme={null}
---
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).


## Related topics

- [Create a knowledge base](/docs/guides/knowledge-base.md)
- [skill.md](/docs/ai/skillmd.md)
- [Customize assistant behavior](/docs/assistant/customize.md)