mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
185979c63d
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
81 lines
4.1 KiB
Plaintext
81 lines
4.1 KiB
Plaintext
---
|
||
title: "添加 assistant skills"
|
||
description: "编写专家级 Markdown 指南（skills），AI 助手在需要时按需加载，使用你的团队手写、有明确观点的内容来回答用户问题并遵循内部规范。"
|
||
keywords: ["assistant", "skills", "loadSkill", "指南", "系统提示"]
|
||
---
|
||
|
||
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
|
||
---
|
||
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/` 目录并重新发布也会清空目录列表。
|