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

> Author expert Markdown guides that the AI assistant loads on demand to answer questions with your team's hand-written, opinionated guidance.

Skills are team-authored Markdown guides that live alongside your documentation. The assistant sees a catalog of your skills in its system prompt and loads the full guide only when a user's question clearly matches one, so you can supply expert, curated answers for the questions that matter most without bloating every response.

Use skills when:

* A topic needs a specific, opinionated answer that generic search results don't produce reliably.
* You want to encode internal playbooks, troubleshooting flows, or migration guides that aren't structured as regular documentation pages.
* You want to shape how the assistant walks users through multi-step or nuanced procedures.

## Add a skill

Create a skill by adding a `skill.md` file inside a slug-named directory under `.mintlify/assistant/skills/`:

```
.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 full guide content:

```markdown .mintlify/assistant/skills/migrate-to-v3/skill.md 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 `name` and `description` to decide whether to load the skill, so write descriptions that clearly state when the guide applies. Keep the body focused: skill content is truncated at roughly 6,000 tokens when loaded.

<Note>
  Skills are discovered on your next documentation update. After you add or change a `skill.md` file, publish your docs to make the skill available to the assistant.
</Note>

## How the assistant uses skills

* The assistant lists every available skill (name, slug, and description) in its system prompt.
* When a user's question matches a skill, the assistant calls the `loadSkill` tool with the skill's slug and uses the returned guide as authoritative context.
* The assistant can load up to three skills per response.
* Loaded skill content is treated as team-authored guidance and takes precedence over general search results.
* On follow-up turns, previously loaded skill content is removed from the conversation history to keep the context small; the assistant reloads a skill if it needs it again.

Skills work alongside [custom assistant instructions](/assistant/customize) in `.mintlify/Assistant.md`. Use `Assistant.md` for global tone, persona, and rules; use skills for deep, topic-specific guidance the assistant should pull in only when relevant.

## Skill authoring tips

* Give each skill a distinct, unambiguous `description`. Overlapping descriptions make it harder for the assistant to pick the right skill.
* Use a unique, URL-safe slug for each directory name. Slugs must contain only lowercase letters, numbers, and hyphens. Duplicate slugs are skipped with a warning during publishing.
* Structure guides with clear headings and numbered steps. Assistants follow procedural content more reliably when it's explicit.
* Keep guides self-contained. The assistant loads one skill at a time, so it should not require another skill to make sense.
* Prefer prose and code samples over screenshots. The assistant only reads the Markdown body.

## Disable skills

Skills are enabled by default when at least one `skill.md` file is present. To turn skills off entirely for your deployment, contact [support](mailto:support@mintlify.com) to disable the assistant skills feature. Removing the `.mintlify/assistant/skills/` directory and republishing also clears the catalog.


## Related topics

- [skill.md](/docs/ai/skillmd.md)
- [Customize assistant behavior](/docs/assistant/customize.md)
- [Assistant](/docs/assistant/index.md)