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/core-concepts/skill-guidelines.md.

Skill 规范

提示

豆包模型负责「听懂用户、做出决策」,开发者负责「提供能力、决定怎么呈现」,而 Skill 说明书就是开发者写给模型看的操作手册——它决定了模型能否在对的时机、用对的工具、出对的卡片,把开发者的服务准确交付给用户。

Skill 是什么

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

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

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

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

Skill 的拆分

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

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

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

Skill 的迭代

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

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

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

正文的五个模块

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

---
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 的注意事项中写清。以下是工具引用的示例:

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

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

手写方式示例(字段应以实际工具定义为准,注意事项与上例相同):

{
  "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 部分。

场景路由与工具编排

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

用户意图处理方式
路线规划、怎么去、多远、多久调用 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,不调用地图工具

多步链路要写清顺序和依赖,比如:

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

按「自由度」选择写法

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

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

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

卡片输出约定

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

Widget id触发工具展示时机
song_cardmusic_search搜索成功后自动下发
VIP_cardmusic_vip命中 VIP 歌曲且用户非 VIP 时下发

失败降级

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

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

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

特别提示

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

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 运行评测,观察触发、填参、出卡和兜底是否符合预期。