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

# Skill 开发

:::info 提示

Skill 是豆包应用插件中供模型理解和使用业务能力的运行态说明。MCP Server 定义工具“能做什么”，Skill 定义模型“什么时候调用、按什么顺序调用、缺少信息时如何追问，以及拿到结果后如何回复用户”。本页主要说明如何在豆包应用插件项目中编写可维护、可验证的 Skill。[Skill 规范](/apps-plugin/docs/core-concepts/skill-guidelines.md)、[MCP 协议](/apps-plugin/docs/skill-development/mcp-server-protocol.md)、[Manifest 字段](/apps-plugin/docs/core-concepts/manifest.md)和[卡片渲染细节](/apps-plugin/docs/frontend-development/widget.md)请分别阅读对应文档。

<div hidden data-lark-callout-end></div>

:::

## 开始前准备

一个完整的应用插件项目至少应具备：

- `skill/`：运行态 Skill，支持一份或多份 `SKILL.md`；
- `manifest.yaml`：工具、实体、权限和卡片绑定配置；
- 可访问的 MCP Server：提供工具列表和工具调用能力；
- 前端工程：实现页面和需要展示的卡片。

运行 `dbx init <directory>` 创建新项目时，CLI 会生成默认的 `skill/SKILL.md`。单 Skill 项目可直接维护该文件；需要多 Skill 时，再按下文的目录结构拆分。修改 Skill 时，应与 MCP 工具、Manifest 和前端卡片改动一起检查。

## Skill 文件结构

只需一份 Skill 时，继续使用默认结构：

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

可运行 `dbx upgrade` 升级 CLI。

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

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

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

## 单文件组织方式

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

| 部分  | 位置                            | 应写内容                         |
| --- | ----------------------------- | ---------------------------- |
| 元数据 | `SKILL.md` 的 YAML frontmatter | Skill 名称和触发场景。               |
| 主体  | `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` 用于描述“何时使用”，而不是介绍实现方式。它应覆盖用户的常见说法、同义表达和明确边界，但不应写入工具名、参数细节或宣传语。

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

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

### 4. 编写主体工作流

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

```markdown
# 订单服务

## 查询订单

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

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”拆分。
