# Add assistant skills (/assistant/skills)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 881 · updated: 2026-07-30 -->
Related: [Configure the assistant](/assistant/configure.md), [Customize assistant behavior](/assistant/customize.md), [Mintlify widget](/assistant/widget.md), [Use the assistant](/assistant/use.md)

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]

Add a `skill.md` file inside a directory named for the skill under `.mintlify/assistant/skills/`:

```text title="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 title=".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 [#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 [#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 [#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).