Skill 开发
Skill 是豆包应用插件中供模型理解和使用业务能力的运行态说明。MCP Server 定义工具“能做什么”,Skill 定义模型“什么时候调用、按什么顺序调用、缺少信息时如何追问,以及拿到结果后如何回复用户”。本页主要说明如何在豆包应用插件项目中编写可维护、可验证的 Skill。Skill 规范、MCP 协议、Manifest 字段和卡片渲染细节请分别阅读对应文档。
开始前准备
一个完整的应用插件项目至少应具备:
skill/:运行态 Skill,支持一份或多份SKILL.md;manifest.yaml:工具、实体、权限和卡片绑定配置;- 可访问的 MCP Server:提供工具列表和工具调用能力;
- 前端工程:实现页面和需要展示的卡片。
运行 dbx init <directory> 创建新项目时,CLI 会生成默认的 skill/SKILL.md。单 Skill 项目可直接维护该文件;需要多 Skill 时,再按下文的目录结构拆分。修改 Skill 时,应与 MCP 工具、Manifest 和前端卡片改动一起检查。
Skill 文件结构
只需一份 Skill 时,继续使用默认结构:
可运行 dbx upgrade 升级 CLI。
需要多份 Skill 时,在 skill/ 下为每份 Skill 创建一个独立子目录:
每个子目录只放一份 SKILL.md,目录名应稳定、易读,并与 Skill 的 name 对应。单 Skill 和多 Skill 均不支持 references/、scripts/、assets/ 等附属目录。所需的规则、字段说明和流程都应写入对应的 SKILL.md;使用标题、短段落和表格保持内容清晰。不要加入 README、版本日志、团队介绍或面向人类的安装说明。
单文件组织方式
将以下内容组织在同一个文件中:
主体应保持简洁,只保留模型完成任务所需的规则。长字段表、重复背景和低价值示例应删减或改写为决策规则,而不是拆到其它文件。
编写流程
1. 明确目标和边界
先写清以下问题,再开始编写正文:
- 用户希望完成什么任务?
- 哪些表达应触发这个 Skill?哪些相似表达不应触发?
- 任务需要哪些工具?它们的调用顺序和依赖关系是什么?
- 信息不足时,应向用户追问什么?
- 成功、无结果、业务失败和权限不足时,应该如何回应?
- 哪些字段可以对模型和用户展示,哪些属于敏感或内部字段?
如果工具、结果形式或触发边界尚未确定,先补齐设计,不要把不确定假设写成强制流程。
2. 选择单 Skill 或多 Skill
优先让一份 Skill 承接相互关联的流程。出现以下任一情况时,可以拆分为多份 Skill:
- 用户的单轮需求通常只会命中其中一组能力,不需要同时使用其他能力;
- 不同能力使用的工具和处理流程相对独立,拆分后可以清楚描述各自的触发边界;
- 删除重复规则和低价值示例后,单份正文仍接近或超过 5,000 tokens。
例如,商品服务中的“搜索与预订”和“售后查询”通常对应不同的用户需求和工具流程,可以分别编写两份 Skill。模型会根据各份 Skill 的 description 选择适合当前请求的能力,因此每份 description 都应写清适用场景和排除边界,避免多份 Skill 同时覆盖相同表达。
以下情况更适合保留一份 Skill:
- 相同业务目标、仅输出风格或少量参数不同:在同一个
SKILL.md中通过条件和分节区分。 - 同一应用插件中的多个流程共享用户、业务上下文或核心工具:在同一个
SKILL.md中分别写明触发条件和执行步骤。 - 业务目标、目标用户、权限边界或交互形态明显不同,且不应共享同一个业务上下文:应规划为多个应用插件;每个应用插件各自维护一个
skill/SKILL.md。
确定如何拆分后,按“Skill 文件结构”创建目录并编写各份 SKILL.md。运行 dbx dev,逐个检查用户输入能否触发正确的 Skill 和工具。准备提交版本时,在项目根目录执行 dbx build,CLI 会读取并打包 skill/ 中的所有 SKILL.md。
frontmatter 中的 name 应与对应 Skill 的能力名称一致,建议使用稳定、可读的 ASCII kebab-case 名称。
3. 编写触发描述
frontmatter 中的 description 用于描述“何时使用”,而不是介绍实现方式。它应覆盖用户的常见说法、同义表达和明确边界,但不应写入工具名、参数细节或宣传语。
好的描述让模型知道触发条件和排除条件;过于宽泛的描述会与相邻 Skill 争抢触发,过于抽象的描述则难以命中真实用户表达。
4. 编写主体工作流
正文应从用户意图出发,按模型实际执行顺序描述。使用短句和明确的条件,而不是堆叠工具名称。
每个流程应说明:何时调用工具、调用前需要什么信息、结果如何解释、何时追问、何时停止。工具真实返回的字段以工具 schema 和结果为准,Skill 不应虚构字段、订单或操作结果。
5. 控制单份 Skill 篇幅
SKILL.md 必须承载完整的运行态说明。为避免文件臃肿,应避免以下内容:
- 完整接口字段表和错误码表;
- 大量枚举值、行业规则或区域化政策;
- 长篇示例对话;
- 与当前任务无关的背景介绍。
保留会影响模型决策的字段、条件和错误处理;其余内容改写为简短规则,或放在运行态 Skill 之外的面向开发者文档中。
与 MCP、Manifest 和卡片的关系
Skill 不替代其它运行时产物:
新增一个可出卡能力时,至少同时确认:Skill 会在正确场景调用工具;MCP 返回的实体符合 Manifest;Manifest 中的工具和实体配置指向已注册的 Widget;卡片能处理成功、空态和失败状态。
质量检查
提交前按以下清单自检:
name、目录名和业务名称一致;description同时包含触发条件和排除边界;- 每份 Skill 的运行态规则都在对应的
SKILL.md中,且正文保持聚焦; - 每一个工具调用都说明前置条件、必要参数和失败处理;
- 不会要求模型猜测工具参数、业务结果或敏感数据;
- 包含至少 2–3 个应触发的用户表达,以及 1–2 个不应触发的表达;
- 涉及登录、支付、个人信息或外部写操作时,明确授权、确认和安全边界;
- 单 Skill 项目的
skill/SKILL.md,或多 Skill 项目的各子目录和SKILL.md,可被项目打包流程读取。
修改 Skill 后,应结合本地调试流程检查常见用户输入、工具调用顺序、追问、错误返回和卡片展示是否符合预期。
常见问题
Skill 没有被正确触发
检查 description 是否只写了抽象业务名,而没有覆盖用户实际说法;同时检查它是否过宽,导致被其他 Skill 抢占。补充典型表达和明确的排除条件。
模型调用了错误工具
检查正文是否只罗列工具名而没有描述选择条件、调用顺序和参数来源。将“何时调用 A、何时调用 B、何时追问”的决策写成明确步骤。
模型编造了字段或结果
检查正文是否写入了工具实际未返回的字段,或未要求模型以工具真实返回为准。删除猜测性描述,并将字段约束收敛到工具 schema 和 SKILL.md 的必要规则中。
Skill 文件过长
不要拆分为附属文件。先删除低频背景和重复示例,合并相近流程,只保留模型命中后必须立即执行的判断和步骤。如果不同流程对应相对独立的用户需求和工具集,且精简后单份正文仍接近或超过 5,000 tokens,可以按“选择单 Skill 或多 Skill”拆分。