跳转到主要内容
Skills 是与你的文档一同存放的、由团队编写的 Markdown 指南。AI 助手会在其系统提示中看到你的 skills 目录列表，仅当用户的问题明显匹配某个 skill 时才会加载完整的指南，这样你就能为最重要的问题提供专家级的精心答案，而不会让每次响应都变得冗长。 在以下情况下使用 skills：
  • 某个主题需要具体的、有明确观点的答案，而通用搜索结果无法可靠地给出。
  • 你希望编码内部操作手册、故障排查流程或迁移指南，而这些内容并不适合作为常规文档页面来组织。
  • 你希望塑造 AI 助手引导用户完成多步骤或细节繁多流程的方式。

​
添加 skill

在 .mintlify/assistant/skills/ 下以 slug 命名的目录中添加一个 skill.md 文件即可创建一个 skill： 
.mintlify/
└── assistant/
    └── skills/
        ├── migrate-to-v3/
        │   └── skill.md
        └── debug-webhooks/
            └── skill.md
每个 skill.md 文件都需要包含 name 和 description 的 YAML frontmatter，随后是完整的指南内容：
.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

...
AI 助手会依据 name 和 description 来决定是否加载该 skill，因此描述应清楚说明该指南何时适用。请让正文保持聚焦：加载时 skill 内容会在约 6,000 tokens 处被截断。
Skills 会在你下一次文档更新时被发现。添加或修改 skill.md 文件后，请发布文档以让 AI 助手能够使用该 skill。

​
AI 助手如何使用 skills

  • AI 助手会在系统提示中列出所有可用的 skill（名称、slug 和描述）。
  • 当用户的问题匹配某个 skill 时，AI 助手会使用该 skill 的 slug 调用 loadSkill 工具，并将返回的指南作为权威上下文。
  • AI 助手每次响应最多可加载三个 skill。
  • 已加载的 skill 内容会被视为团队编写的权威指导，其优先级高于通用搜索结果。
  • 在后续对话轮次中，之前加载的 skill 内容会从对话历史中移除以保持上下文精简；如果 AI 助手再次需要，会重新加载该 skill。
Skills 与 .mintlify/Assistant.md 中的自定义 AI 助手指令协同工作。将 Assistant.md 用于全局语气、角色和规则；将 skills 用于 AI 助手仅在相关时才需要引入的、面向特定主题的深入指导。

​
Skill 编写建议

  • 为每个 skill 编写独特、无歧义的 description。描述内容重叠会让 AI 助手更难挑选出正确的 skill。
  • 为每个目录名使用唯一且 URL 安全的 slug。Slug 只能包含小写字母、数字和连字符。重复的 slug 会在发布时被跳过并给出警告。
  • 用清晰的标题和编号步骤来组织指南结构。当过程性内容明确时，AI 助手能更可靠地遵循。
  • 让指南保持自包含。AI 助手一次只加载一个 skill，因此它不应依赖另一个 skill 才能理解。
  • 优先使用文字叙述和代码示例，而非截图。AI 助手只会读取 Markdown 正文。

​
禁用 skills

当至少存在一个 skill.md 文件时，skills 会默认启用。若要完全关闭部署中的 skills 功能，请联系技术支持以禁用 assistant skills 功能。移除 .mintlify/assistant/skills/ 目录并重新发布也会清空目录列表。

相关主题

skill.md自定义 AI 助手行为什么是 agent？