For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/skill-development/overview.md.

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 时,继续使用默认结构:

skill/
└── SKILL.md               # 触发条件、工作流和边界

可运行 dbx upgrade 升级 CLI。

需要多份 Skill 时,在 skill/ 下为每份 Skill 创建一个独立子目录:

skill/
├── search-booking/
│   └── SKILL.md           # 搜索与预订
└── after-sales/
    └── SKILL.md           # 售后查询

每个子目录只放一份 SKILL.md,目录名应稳定、易读,并与 Skill 的 name 对应。单 Skill 和多 Skill 均不支持 references/、scripts/、assets/ 等附属目录。所需的规则、字段说明和流程都应写入对应的 SKILL.md;使用标题、短段落和表格保持内容清晰。不要加入 README、版本日志、团队介绍或面向人类的安装说明。

单文件组织方式

将以下内容组织在同一个文件中:

部分位置应写内容
元数据SKILL.md 的 YAML frontmatterSkill 名称和触发场景。
主体SKILL.md 正文适用范围、核心流程、工具顺序、追问、失败处理和输出要求。

主体应保持简洁,只保留模型完成任务所需的规则。长字段表、重复背景和低价值示例应删减或改写为决策规则,而不是拆到其它文件。

编写流程

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 用于描述“何时使用”,而不是介绍实现方式。它应覆盖用户的常见说法、同义表达和明确边界,但不应写入工具名、参数细节或宣传语。

---
name: order-service
description: 用户查询订单状态、查看订单详情、申请退款或追踪退款进度时使用;不处理商品推荐、创建订单或非本应用订单。
---

好的描述让模型知道触发条件和排除条件;过于宽泛的描述会与相邻 Skill 争抢触发,过于抽象的描述则难以命中真实用户表达。

4. 编写主体工作流

正文应从用户意图出发,按模型实际执行顺序描述。使用短句和明确的条件,而不是堆叠工具名称。

# 订单服务

## 查询订单

当用户询问订单状态或详情时:

1. 若用户未提供可唯一定位订单的信息,询问订单号或可用的筛选条件。
2. 调用 `get_order` 查询订单。
3. 找到订单时,说明订单状态、关键时间和下一步;需要展示订单卡片时遵循 Manifest 的实体和卡片绑定配置。
4. 未找到订单时,说明未找到的原因并提示用户检查订单信息;不要编造订单状态。

## 申请退款

1. 先确认订单是否支持退款,以及用户希望退全款还是部分退款。
2. 调用 `create_refund`,并使用工具返回的退款单号确认受理结果。
3. 工具返回失败时,按返回的错误信息说明原因;不要承诺一定退款成功。

每个流程应说明:何时调用工具、调用前需要什么信息、结果如何解释、何时追问、何时停止。工具真实返回的字段以工具 schema 和结果为准,Skill 不应虚构字段、订单或操作结果。

5. 控制单份 Skill 篇幅

SKILL.md 必须承载完整的运行态说明。为避免文件臃肿,应避免以下内容:

  • 完整接口字段表和错误码表;
  • 大量枚举值、行业规则或区域化政策;
  • 长篇示例对话;
  • 与当前任务无关的背景介绍。

保留会影响模型决策的字段、条件和错误处理;其余内容改写为简短规则,或放在运行态 Skill 之外的面向开发者文档中。

与 MCP、Manifest 和卡片的关系

Skill 不替代其它运行时产物:

产物职责
Skill解释触发场景、工具编排、追问和结果表达。
MCP Server暴露工具、校验输入并执行真实业务逻辑。
Manifest声明工具输出、实体 schema、权限和卡片绑定。
Widget / Page展示卡片和全页交互。

新增一个可出卡能力时,至少同时确认: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”拆分。