> 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 说明书就是开发者写给模型看的操作手册——它决定了模型能否在对的时机、用对的工具、出对的卡片，把开发者的服务准确交付给用户。

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

:::

## Skill 是什么

Skill 说明书是一份用自然语言（Markdown）写成的文档，它告诉豆包模型四件事：**你的服务能做什么、什么时候该启用、每一步怎么调用工具、结果怎么呈现成卡片**。Skill 负责把「零散的工具能力」组织成「可靠服务流程」。

以下是 Skill 的标准结构，**本期豆包应用插件仅支持 Level 1 和 Level 2 二级加载**，后续会逐步支持三级加载

| 级别                     | 内容                             | 加载时机                                     | 体量          |
| ---------------------- | ------------------------------ | ---------------------------------------- | ----------- |
| **Level 1  <br/>元数据**  | YAML 中的 `name` + `description` | **sp 常驻部分 skills + search 后动态加载 skills** | 约 500 token |
| **Level 2  <br/>正文**   | 完整 `SKILL.md` 正文               | 任务匹配 description、**触发时**读入               | \< 5K token |
| **Level 3  <br/>捆绑资源** | `references/`、`assets/` 等文件    | **按需**加载（执行时被引用才读）                       | 没有强限制       |

:::info 提示

豆包侧**暂时不提供沙箱**，Skill 里不能假设可以跑脚本、装包或执行代码。你的所有能力都要通过 **MCP 工具**暴露出来。我们**强烈建议每个服务都配备工具**：一旦涉及查询、交易、状态变更，就必须走工具，让工具的返回作为唯一的事实依据。

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

:::

## Skill 的拆分

和写代码一样，Skill 也要控制单份体量。模型启动时会预加载所有 Skill 的 `name` 和 `description`，命中后才读正文。**正文越长，越挤占上下文，也越容易读到一半就开始执行。**&#x5EFA;议单份正文控制在 **5,000 tokens 以内**，超过后应拆分。

目前，建议按照“能承接用户单轮次需求范围的工具集”来确定拆分方式，尽量让单轮对话仅需调用一次 Skill（可以在 Skill 中调用多次工具）。例如，对于商品销售类的应用插件，“搜索预订”和“售后查询”通常不会出现在同一句 Query 中。如果 5,000 tokens 不足以描述所有模型指引，可以拆成两份。

如果一份 Skill 即可覆盖需求，建议仅提供一份 Skill，这通常有助于获得更好的用户体验。

## Skill 的迭代

写 Skill 不是“一次写对”，而是“先搭对骨架，再迭代打磨”。建议先形成初步的 Skill 版本，再使用本地模拟器观察 Skill 与工具能否在指定 Query 下配合产出预期结果，然后决定如何调整。不要仅根据个人偏好修改。

<table><colgroup><col/><col/></colgroup><thead><tr><th vertical-align="top">步骤</th><th vertical-align="top">要做的事</th></tr></thead><tbody><tr><td vertical-align="top">1. 收集信息</td><td vertical-align="top">先想清楚：能力范围（解决什么问题）、触发 Query（用户会怎么说）、输入输出（要哪些信息、产出什么）、工具依赖（调哪些工具、有无先后顺序）、安全约束（哪些不可逆、哪些要追问、哪些禁止编造）</td></tr><tr><td vertical-align="top">2. 判断粒度</td><td vertical-align="top">按“Skill 的拆分”原则决定合并还是拆分</td></tr><tr><td vertical-align="top">3. 写 description</td><td vertical-align="top">最关键的一步。先把触发边界定清楚：需要覆盖高频说法与多轮指代，写明排除项，第三人称、200 字以内</td></tr><tr><td vertical-align="top">4. 写正文</td><td vertical-align="top">固定顺序：场景路由 → 通用规则 → 逐个工具 → 注意事项</td></tr><tr><td vertical-align="top">5. 梳理场景逻辑</td><td vertical-align="top">正向、反向、边界各 1~2 个，这里建议以提炼核心逻辑为主，<b>尽量</b><b>不使用 few-shot</b><b>（避免过拟合）</b><ul><li><b>正向示例</b>：标准命中时怎么处理。</li><li><b>反向示例</b>：不该触发、不该出卡的情形。</li><li><b>边界示例</b>：多候选、缺信息、失败降级等临界情况怎么走。</li></ul></td></tr><tr><td vertical-align="top">6. 自检准出</td><td vertical-align="top">核对命名、粒度、description 准确性、清晰度、安全性，通过后再上线</td></tr></tbody></table>

:::info 提示

贯穿全程的方法论：**先建评测、再迭代**。用几个代表性 Query 跑一遍，观察模型是否在正确的时机触发、填写正确的参数、输出正确的卡片并正确兜底，再根据问题修改 Skill。写 Skill 始终是“观察真实行为 → 精炼”的循环，而不是一次性堆叠规则。

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

:::

## 正文的五个模块

一份「Skill + 工具」的正文通常包含如下模块

```yaml
---
name: apps-plugin-taxi-caocao
description: 用不超过 300 个中文字符描述触发条件：什么用户场景、什么表达、什么任务应该使用该 Skill。不要写执行步骤、工具链、实现细节或宣传语。

---

# 技能名字

## 通用规则
对于该skill内所有工具均适用的规则，需要模型特别关注的规则

## 场景路由
使用该 Skill 当：
- 场景 1。
- 场景 2。

不要使用该 Skill 当：
- 不适用场景 1；应使用什么替代能力。

## 回复与卡片规则
在什么情况下应该输出什么样的文本，应该如何展示卡片

工具1：xxx

### 工具说明与使用场景
工具能力与预期使用场景的简要说明

### 注意事项
填参规范与特殊情况

### 工具信息（引用或手写，二选一）
使用 {{tool:工具1的名称}}，或手写工具名称、描述和完整 inputSchema

工具2：xxx

### 工具说明与使用场景
工具能力与预期使用场景的简要说明

### 注意事项
填参规范与特殊情况

### 工具信息（引用或手写，二选一）
使用 {{tool:工具2的名称}}，或手写工具名称、描述和完整 inputSchema

……

## 通用注意事项
```

### 能力范围（name + description）

开头的 `name` 和 `description` 是模型选择 Skill 的**主要依据**，决定了「能不能被触发」。紧跟其后的概述用一两段话圈定能力边界——**既写清做什么，也写清不做什么**。

- `name`

  - 限制：字符数不超过 64 个（token 数不超过 30，64 × 0.48），纯文本
  - 命名规范：doubao/agentic-service-任务名-（补充说明），建议用动词短语，体现服务与能力域

    - 豆包一方：doubao-任务名，例如：doubao-map-navigation，注意结尾不用到 skills
    - 外部合作伙伴：apps-plugin-任务名，例如：apps-plugin-taxi-caocao
- `description`

  - 限制：建议尽量控制在 300 个字符以内（token 不超过 0.15K）；纯文本
  - 撰写规范：描述能力和使用场景，**要写** what + when + 触发上下文

    1. **必须使用第三人称。**`description` 会被注入到 system prompt 中，若叙述视角不一致，可能导致发现或路由问题。

       - ✅ 处理 Excel 文件并生成报告
       - ❌ 我可以帮你处理 Excel 文件（第一人称）
       - ❌ 你可以用这个来处理 Excel 文件（第二人称）
    2. **必须同时包含 “做什么（what）” 和 “何时使用（when）”**，并写明关键触发词或上下文，比如：

       - 从 PDF 文件中提取文本和表格、填写表单、合并文档。当处理 PDF 文件，或用户提到 PDF、表单、文档提取时使用。
       - 分析 Excel 电子表格、创建数据透视表、生成图表。当分析 Excel 文件、电子表格、表格型数据或 `.xlsx` 文件时使用。
    3. **描述要具体，避免含糊**。反例：帮助处理文档 / 处理数据 / 处理各类文件 —— 这类表述过于笼统，无法支持准确的路由判断。
    4. **不写交互话术：**`description` 只描述能力与适用场景，把“追问、出卡”等行为逻辑留在正文，不写入 `description`。

### 工具入参

Skill 正文中的工具信息可以通过以下两种方式提供：

- **工具引用**：使用 `{{tool:xxx}}`，其中 `xxx` 替换为工具在 MCP Server / Tool 配置中的名称。发布时，平台会自动将占位符展开为工具的名称、描述和 `inputSchema`，无需重复手写这些信息。
- **手写工具信息**：直接在 Skill 中编写工具名称、描述和完整 `inputSchema`，并确保与工具定义保持一致。

无论使用哪种方式，`inputSchema` 都需要完整描述字段取值、必填/可选和格式；填参规则、调用前置条件及工具间依赖等仍需在 Skill 的注意事项中写清。以下是工具引用的示例：

```markdown
## 工具:navigate_command
### 工具引用
{{tool:navigate_command}}

### 注意
1. 启动导航前必须先调 route_plan_v2 拿到 entity_id。
2. stop_navi 不需要 entity_id。
```

手写方式示例（字段应以实际工具定义为准，注意事项与上例相同）：

```json
{
  "name": "navigate_command",
  "description": "启动或停止导航",
  "inputSchema": {
    "type": "object",
    "properties": {
      "command": {
        "type": "string",
        "enum": ["start_navi", "stop_navi"],
        "description": "start_navi 启动导航，stop_navi 停止导航"
      },
      "start_navi_args": {
        "type": "object",
        "description": "启动导航时必填，停止导航时省略",
        "properties": {
          "entity_id": {
            "type": "string",
            "description": "route_plan_v2 返回的路线 entity_id"
          },
          "app_name": {
            "type": "string",
            "enum": ["amap", "baidu", "bytemap"],
            "description": "导航应用，用户未指定时省略"
          }
        },
        "required": ["entity_id"]
      }
    },
    "required": ["command"]
  }
}
```

具体工具及入参的设计建议可以参考 MCP Server 部分。

### 场景路由与工具编排

这是正文的核心。先用一&#x5F20;**「用户意图 → 处理方式」的路由表**把常见意图一次罗列清楚，让模型一眼看到全貌、不漏处理；再针对复杂链路补充有序步骤。比如：

| 用户意图              | 处理方式                                         |
| ----------------- | -------------------------------------------- |
| 路线规划、怎么去、多远、多久    | 调用 route\_plan\_v2                           |
| 「导航去 X」「带我去 X」等问路 | 只调 route\_plan\_v2 出路线卡，不调 navigate\_command |
| 「发起/开始/立即导航」等执行动作 | 先 route\_plan\_v2 取路线，再调 navigate\_command   |
| 我在哪、当前位置          | 调用 locate                                    |
| 附近 xxx、xxx 在哪、哪里有 | 调 local\_search，再调 map\_mark 出 POI 卡         |
| 打车费用、叫车 ETA       | 不属于本 Skill，不调用地图工具                           |

多步链路要写清**顺序和依赖，比如**：

```xml
## 工具编排(咖啡点单)
1. 没指定门店 → 先调 list_nearby_stores 取最近一家。
2. 没点名商品(如"随便一杯果味的") → 调 list_products 挑选。
3. 门店和商品都定了 → 调 create_order 生成预估单，出订单确认卡。
4. 用户问进度 → 调 query_order，出订单状态卡。
```

**按「自由度」选择写法**

同一个路由，并不总是写得越死越好。可以&#x6309;**“留给模型多少自主空间”**&#x5206;为三档，分别使用不同写法。判断依据很简单：操作是否可逆、出错代价是否较高、路径是否唯一。

| 自由度   | 典型场景                          | 推荐写法                             |
| ----- | ----------------------------- | -------------------------------- |
| 低（写死） | 下单、支付、改单、删除等不可逆或高代价操作，有唯一正确路径 | 写成明确的有序步骤或决策表，把每一步、每个边界、每种失败都规定死 |
| 中     | 多步编排但允许少量分支，路径大体固定            | 给带条件分支的步骤 + 决策表，关键约束用规则兜住，细节交给模型 |
| 高（放开） | 查询、检索、推荐、解释等可逆、低风险、答案不唯一      | 只写目标、边界和红线，给几个示例，把具体表达和顺序交给模型    |

一个重要前提：**默认模型是聪明的**。高自由度场景写太多规则，反而会限制模型、增加 token、制造自相矛盾。真正需要写死的，是那些**做错就无法挽回、或有唯一正确做法**的低自由度动作。地图里「导航去 X 只出路线卡、发起导航才调 navigate\_command」就是典型的写死；而「附近有什么好吃的」只需约束「先 local\_search 再 map\_mark、不得编造 POI」即可。

### 卡片输出约定

豆包服务主要靠对话内卡片呈现。要写&#x6E05;**「什么工具、什么时机、出什么卡、用什么格式引用」**，卡片内的 `id` 等信息**必须来自工具返回**，不能编造。卡片类型和时机建议用表格声明，比如：

| Widget id  | 触发工具          | 展示时机                  |
| ---------- | ------------- | --------------------- |
| song\_card | music\_search | 搜索成功后自动下发             |
| VIP\_card  | music\_vip    | 命中 VIP 歌曲且用户非 VIP 时下发 |

### 失败降级

没有沙箱、依赖外部工具，失败是常态。**每一类失败都要写明「如实回复 + 下一步建议」**，严禁把失败伪装成成功、严禁编造数据补位。

```xml
## 工具失败时的如实回复
- 工具失败、无返回、结果为空、status 非 success 时:
  说明未成功，不出卡片，不编造成功结论。
- 搜索无结果 → 建议用户换关键词、换区域或补充更具体的名称。
- 下单类工具: 只有返回成功才能说"已下单"; 失败不得说已完成。
```

:::info 提示

进阶：有条件时可以设计**降级链路**。例如音乐场景「站内搜不到 → 降级用公共检索给外链」；但要划清红线（哪些场景禁止降级、外链白/黑名单），避免让降级带来新的合规或体验问题。

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

:::

## 特别提示

下面几条不属于某个具体模块，却是最常翻车的地方，根因大多是同一个：**规则写得越多越乱，反而越不可靠**。

**1. 同一件事只写一处**

不要在总纲、场景路由、工具注意事项里把同一条规则写三遍。重复不仅费 token，更危险的是——**一处改了、别处没改，就会前后矛盾，模型无所适从**。公共规则只在总纲写一次，工具的边界只在该工具章节写，需要引用时指过去就行。

**2. 写完自检前后矛盾**

常见冲突：路由说「导航去 X 只出路线卡」，工具章节却说「命中导航就调 navigate\_command」；或 A 处说「缺目的地必须追问」，B 处又说「缺目的地默认取最近 POI」。上线前通读一遍，重点核对：同一意图在不同章节是否一致、追问与继续的边界是否划一致、示例是否和规则一致。**矛盾的规则比没有规则更糟**。

**3. 多用正向指令，少堆禁令**

优先写「该怎么做」，而不是罗列一长串「不要做什么」。正向、具体的指令模型更好执行；禁令只作关键红线的补充，点到即止（如「不得编造 poi\_id」）。

**4. 剔除噪音**

Skill 是行为准则，不是产品文档。和「模型该怎么做」无关的背景介绍、营销话术都该删掉。默认模型已经聪明，常识不用教，只写它不知道的：你的工具怎么调、边界在哪、失败怎么兜。

**5. 不要硬编码时效性内容**

避免「X 月前用旧接口」这类会过期的规则，一旦过期就成了没人察觉的错误规则。时效性逻辑交给工具返回或运行时判断。

## 上线前自检清单

- 涉及实时、交易或状态变更的服务都使用“Skill + 工具”，不使用纯 Skill。
- 单份正文不超过 5,000 tokens；拆分后的二层文件与主文之间仅相隔一层。
- `description` 使用第三人称，不超过 200 个字，覆盖能力、高频触发词和多轮指代，写明排除项，不使用扩张性措辞。
- 有场景路由表；复杂链路写清了顺序与依赖；按自由度选了合适写法。
- 私有工具通过 `{{tool:xxx}}` 引用完整 Schema，或手写并与工具定义保持一致；公共工具只约束使用时机，不重写 Schema。
- 卡片协议写清：成功才出卡、开场 + 卡片、不泄漏内部字段。
- 每类失败都有「如实回复 + 下一步建议」，不编造补位。
- 同一件事只写一处，通读无前后矛盾，正向指令为主。
- 使用代表性 Query 运行评测，观察触发、填参、出卡和兜底是否符合预期。
