Skill 规范
豆包模型负责「听懂用户、做出决策」,开发者负责「提供能力、决定怎么呈现」,而 Skill 说明书就是开发者写给模型看的操作手册——它决定了模型能否在对的时机、用对的工具、出对的卡片,把开发者的服务准确交付给用户。
Skill 是什么
Skill 说明书是一份用自然语言(Markdown)写成的文档,它告诉豆包模型四件事:你的服务能做什么、什么时候该启用、每一步怎么调用工具、结果怎么呈现成卡片。Skill 负责把「零散的工具能力」组织成「可靠服务流程」。
以下是 Skill 的标准结构,本期豆包应用插件仅支持 Level 1 和 Level 2 二级加载,后续会逐步支持三级加载
豆包侧暂时不提供沙箱,Skill 里不能假设可以跑脚本、装包或执行代码。你的所有能力都要通过 MCP 工具暴露出来。我们强烈建议每个服务都配备工具:一旦涉及查询、交易、状态变更,就必须走工具,让工具的返回作为唯一的事实依据。
Skill 的拆分
和写代码一样,Skill 也要控制单份体量。模型启动时会预加载所有 Skill 的 name 和 description,命中后才读正文。正文越长,越挤占上下文,也越容易读到一半就开始执行。建议单份正文控制在 5,000 tokens 以内,超过后应拆分。
目前,建议按照“能承接用户单轮次需求范围的工具集”来确定拆分方式,尽量让单轮对话仅需调用一次 Skill(可以在 Skill 中调用多次工具)。例如,对于商品销售类的应用插件,“搜索预订”和“售后查询”通常不会出现在同一句 Query 中。如果 5,000 tokens 不足以描述所有模型指引,可以拆成两份。
如果一份 Skill 即可覆盖需求,建议仅提供一份 Skill,这通常有助于获得更好的用户体验。
Skill 的迭代
写 Skill 不是“一次写对”,而是“先搭对骨架,再迭代打磨”。建议先形成初步的 Skill 版本,再使用本地模拟器观察 Skill 与工具能否在指定 Query 下配合产出预期结果,然后决定如何调整。不要仅根据个人偏好修改。
贯穿全程的方法论:先建评测、再迭代。用几个代表性 Query 跑一遍,观察模型是否在正确的时机触发、填写正确的参数、输出正确的卡片并正确兜底,再根据问题修改 Skill。写 Skill 始终是“观察真实行为 → 精炼”的循环,而不是一次性堆叠规则。
正文的五个模块
一份「Skill + 工具」的正文通常包含如下模块
能力范围(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 + 触发上下文
-
必须使用第三人称。
description会被注入到 system prompt 中,若叙述视角不一致,可能导致发现或路由问题。- ✅ 处理 Excel 文件并生成报告
- ❌ 我可以帮你处理 Excel 文件(第一人称)
- ❌ 你可以用这个来处理 Excel 文件(第二人称)
-
必须同时包含 “做什么(what)” 和 “何时使用(when)”,并写明关键触发词或上下文,比如:
- 从 PDF 文件中提取文本和表格、填写表单、合并文档。当处理 PDF 文件,或用户提到 PDF、表单、文档提取时使用。
- 分析 Excel 电子表格、创建数据透视表、生成图表。当分析 Excel 文件、电子表格、表格型数据或
.xlsx文件时使用。
-
描述要具体,避免含糊。反例:帮助处理文档 / 处理数据 / 处理各类文件 —— 这类表述过于笼统,无法支持准确的路由判断。
-
不写交互话术:
description只描述能力与适用场景,把“追问、出卡”等行为逻辑留在正文,不写入description。
-
-
工具入参
Skill 正文中的工具信息可以通过以下两种方式提供:
- 工具引用:使用
{{tool:xxx}},其中xxx替换为工具在 MCP Server / Tool 配置中的名称。发布时,平台会自动将占位符展开为工具的名称、描述和inputSchema,无需重复手写这些信息。 - 手写工具信息:直接在 Skill 中编写工具名称、描述和完整
inputSchema,并确保与工具定义保持一致。
无论使用哪种方式,inputSchema 都需要完整描述字段取值、必填/可选和格式;填参规则、调用前置条件及工具间依赖等仍需在 Skill 的注意事项中写清。以下是工具引用的示例:
手写方式示例(字段应以实际工具定义为准,注意事项与上例相同):
具体工具及入参的设计建议可以参考 MCP Server 部分。
场景路由与工具编排
这是正文的核心。先用一张「用户意图 → 处理方式」的路由表把常见意图一次罗列清楚,让模型一眼看到全貌、不漏处理;再针对复杂链路补充有序步骤。比如:
多步链路要写清顺序和依赖,比如:
按「自由度」选择写法
同一个路由,并不总是写得越死越好。可以按“留给模型多少自主空间”分为三档,分别使用不同写法。判断依据很简单:操作是否可逆、出错代价是否较高、路径是否唯一。
一个重要前提:默认模型是聪明的。高自由度场景写太多规则,反而会限制模型、增加 token、制造自相矛盾。真正需要写死的,是那些做错就无法挽回、或有唯一正确做法的低自由度动作。地图里「导航去 X 只出路线卡、发起导航才调 navigate_command」就是典型的写死;而「附近有什么好吃的」只需约束「先 local_search 再 map_mark、不得编造 POI」即可。
卡片输出约定
豆包服务主要靠对话内卡片呈现。要写清「什么工具、什么时机、出什么卡、用什么格式引用」,卡片内的 id 等信息必须来自工具返回,不能编造。卡片类型和时机建议用表格声明,比如:
失败降级
没有沙箱、依赖外部工具,失败是常态。每一类失败都要写明「如实回复 + 下一步建议」,严禁把失败伪装成成功、严禁编造数据补位。
进阶:有条件时可以设计降级链路。例如音乐场景「站内搜不到 → 降级用公共检索给外链」;但要划清红线(哪些场景禁止降级、外链白/黑名单),避免让降级带来新的合规或体验问题。
特别提示
下面几条不属于某个具体模块,却是最常翻车的地方,根因大多是同一个:规则写得越多越乱,反而越不可靠。
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 运行评测,观察触发、填参、出卡和兜底是否符合预期。