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

# 添加 assistant skills

> 编写专家级的 Markdown 指南，AI 助手会按需加载这些指南，用你的团队手写、有明确观点的内容来回答问题。

Skills 是与你的文档一同存放的、由团队编写的 Markdown 指南。AI 助手会在其系统提示中看到你的 skills 目录列表，仅当用户的问题明显匹配某个 skill 时才会加载完整的指南，这样你就能为最重要的问题提供专家级的精心答案，而不会让每次响应都变得冗长。

在以下情况下使用 skills：

* 某个主题需要具体的、有明确观点的答案，而通用搜索结果无法可靠地给出。
* 你希望编码内部操作手册、故障排查流程或迁移指南，而这些内容并不适合作为常规文档页面来组织。
* 你希望塑造 AI 助手引导用户完成多步骤或细节繁多流程的方式。

<div id="add-a-skill">
  ## 添加 skill
</div>

在 `.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，随后是完整的指南内容：

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

...
```

AI 助手会依据 `name` 和 `description` 来决定是否加载该 skill，因此描述应清楚说明该指南何时适用。请让正文保持聚焦：加载时 skill 内容会在约 6,000 tokens 处被截断。

<Note>
  Skills 会在你下一次文档更新时被发现。添加或修改 `skill.md` 文件后，请发布文档以让 AI 助手能够使用该 skill。
</Note>

<div id="how-the-assistant-uses-skills">
  ## AI 助手如何使用 skills
</div>

* AI 助手会在系统提示中列出所有可用的 skill（名称、slug 和描述）。
* 当用户的问题匹配某个 skill 时，AI 助手会使用该 skill 的 slug 调用 `loadSkill` 工具，并将返回的指南作为权威上下文。
* AI 助手每次响应最多可加载三个 skill。
* 已加载的 skill 内容会被视为团队编写的权威指导，其优先级高于通用搜索结果。
* 在后续对话轮次中，之前加载的 skill 内容会从对话历史中移除以保持上下文精简；如果 AI 助手再次需要，会重新加载该 skill。

Skills 与 `.mintlify/Assistant.md` 中的[自定义 AI 助手指令](/zh/assistant/customize)协同工作。将 `Assistant.md` 用于全局语气、角色和规则；将 skills 用于 AI 助手仅在相关时才需要引入的、面向特定主题的深入指导。

<div id="skill-authoring-tips">
  ## Skill 编写建议
</div>

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

<div id="disable-skills">
  ## 禁用 skills
</div>

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


## Related topics

- [skill.md](/docs/zh/ai/skillmd.md)
- [自定义 AI 助手行为](/docs/zh/assistant/customize.md)
- [什么是 agent？](/docs/zh/agent/index.md)