Skip to main content
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:
.mintlify/assistant/skills/migrate-to-v3/skill.md
---
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.
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.

​
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 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 to disable the assistant skills feature. Removing the .mintlify/assistant/skills/ directory and republishing also clears the catalog.

Related topics

skill.mdCustomize assistant behaviorAssistant