文档中心/ 百度搭子/ 生态开放平台指南/ 开发标准/ 技能(Skill)

技能(Skill)

本文说明 百度搭子 技能(Skill)的结构、编写方式、测试方法和安全要求,供开发者参考。

适用对象

  • 想为百度搭子新技能的开发者
  • 需要调整触发词、执行流程或测试用例的开发者
  • 需要接入工具或外部服务的开发者

最小结构

最小结构如下:

Text
1daily-summary/
2├── SKILL.md
3└── tests/
4    └── cases.json

可选目录如下:

  • scripts/:存放确定性脚本,例如数据处理、接口调用
  • references/:存放静态参考资料,例如长文档、接口说明、业务规则
  • assets/:存放图标、模板和其他静态资源

编写 SKILL.md

SKILL.md 是技能的核心,它同时承担“入口说明”和“执行指令”两种角色。

先写 name 和 description

  • name 建议用 kebab-case,例如 daily-summary,并与文件夹名保持一致。
  • description 决定这个技能是否会被正确触发。

推荐公式:

YAML
1description: |
2  [一句话说明这个技能做什么]。
3  用户说出“[常见说法1]”“[常见说法2]”“[常见说法3]”时使用。
4  不触发:[容易混淆但不属于本技能的场景]。

写法原则:

  • 使用用户真实会说的话,不用内部术语
  • 覆盖正式说法和口语说法
  • 明确写出不该触发的场景

示例:

YAML
1description: |
2  从已有联系人中搜索信息,并返回联系方式和最近互动记录。
3  用户说出“查一下这个客户”“CRM 里有没有这个人”“找找某公司的联系方式”时使用。
4  不触发:新增联系人、编辑客户信息、查询公开公司信息。

元数据示例

YAML
1---
2name: daily-summary
3description: |
4  根据用户提供的当天经历,生成简洁的每日总结。
5  用户说出“今天总结一下”“帮我记录今天”“日记”“今日回顾”时使用。
6  不触发:单纯闲聊、天气查询、与总结无关的信息检索。
7
8metadata:
9  dumate:
10    displayName: "每日总结"
11    summary: "将用户当天的工作和生活经历整理成结构化总结,适合记录、回顾和复盘。"
12    publisher: "DuMate"
13    icon: "assets/icon.png"
14    publishedAt: 1775619720000
15    version: "1.0.0"
16    level: L0
17    category: 内容创作
18    tags: ["摘要"]
19    sensitive: false
20    allow_implicit_invocation: true
21---

说明:不同版本的元数据字段可能略有差异,发布前请以百度搭子界面中的校验提示为准。

编写执行指令

执行指令负责定义技能触发后的处理方式。建议用清晰的步骤写法,避免模糊表达。

推荐结构:

Markdown
1## 执行指令
2
3### 步骤 1 - 信息确认
4如果缺少必要信息,先向用户追问。
5
6### 步骤 2 - 执行任务
7按既定格式完成输出。
8
9### 步骤 3 - 执行前确认
10如果涉及向外部系统发送内容、删除数据、写入记录或修改已有数据,先展示完整内容并等待用户确认。
11
12### 输出格式
13明确说明最终结果应该长什么样。

编写建议:

  • 用祈使句,直接告诉模型要做什么
  • 能并行的步骤分开写
  • 向外部系统写入或执行不可逆操作时,必须写确认
  • 需要引用外部资料时,说明从哪里读、怎么用

写好降级策略

如果技能依赖外部工具或外部服务,就要提前写好降级逻辑。

常见的三种方式:

类型 适用场景 处理方式
degrade 可用替代方案完成任务 改用基础能力继续输出
partial 只能拿到部分数据 说明缺失内容并返回已有结果
block 写入、发送、删除、鉴权失败 明确停止并提示用户处理后重试

处理规则:

  • 能替代就降级
  • 只能部分完成就部分返回
  • 有风险的写操作就停止

给出例子

至少提供 1 个完整示例,建议覆盖主流程和边界情况。

Markdown
1## 示例
2
3**用户**:帮我总结一下今天,上午开了产品评审会,下午和客户聊了需求。
4
5**DuMate**:
6**2026-06-01 每日总结**
71. 今日要点:产品评审会 / 客户需求沟通
82. 感受与收获:今天推进了两个重要事项,值得整理后续跟进内容
93. 明日计划:如有待办,可继续补充

编写 tests/cases.json

cases.json 用来验证两个问题:

  1. 这个技能该不该触发
  2. 触发后做得对不对

推荐结构如下:

JSON
1{
2  "skill": "daily-summary",
3  "version": "1.0.0",
4  "test_cases": [
5    {
6      "id": "TC001",
7      "name": "标准输入",
8      "category": "happy_path",
9      "input": {
10        "user_message": "帮我记录今天,开了个评审会"
11      },
12      "expected": {
13        "trigger_skill": true,
14        "output_contains": ["总结", "要点"]
15      }
16    },
17    {
18      "id": "TC002",
19      "name": "负向场景",
20      "category": "negative",
21      "input": {
22        "user_message": "今天天气怎么样"
23      },
24      "expected": {
25        "trigger_skill": false
26      }
27    }
28  ]
29}

建议每个技能至少包含:

  • happy_path
  • negative

如果涉及写操作,再补上:

  • 用户确认后执行
  • 用户拒绝时不执行

如果依赖外部工具,再补上:

  • 工具可用时的增强路径
  • 工具不可用时的降级路径

常用断言字段:

字段 说明
trigger_skill 是否应该触发当前技能
output_contains 输出中应包含的关键词
asks_clarification 是否需要追问缺失信息
connected_tools 模拟已连接的工具或服务
calls_tool 期望调用的工具
does_not_call 不应调用的工具
uses_fallback 是否进入降级逻辑
fallback_type 降级类型,例如降级(degrade)、部分返回(partial)、停止(block)

工具接入与复杂流程

当技能只需要生成文本时,尽量保持简单。

如果需要调用外部服务,建议把稳定、重复、易出错的部分封装成脚本,再在执行指令中说明调用顺序。

什么时候写脚本

  • 需要确定性输出
  • 操作有副作用
  • 处理顺序不能错
  • 逻辑太长,模型容易写偏

什么时候保持自然语言

  • 只要阅读和总结
  • 只要轻量判断
  • 结果不依赖精确流程

分级参考

级别 特点
L0 只靠模型本身完成
L1 结合基础工具,例如搜索、文件处理
L2 需要调用外部服务
L3 基础工具和外部服务都要用

安全与合规

发布时,优先保证可验证、可回退、最小权限。

原则:

  • 只处理完成任务必须的数据
  • 不要暴露密码、访问令牌、接口密钥等敏感信息
  • 向外部系统写入或执行不可逆操作时先确认
  • 不要虚构来源、结果或执行记录
  • 涉及隐私、财务、医疗等内容时要更谨慎

如果外部服务不可用,宁可明确说明,也不要编造结果。

如果需要外部授权,请使用平台提供的标准凭证方案,不要在技能指令、示例或错误提示中暴露密钥、凭证路径或其他敏感实现细节。

开发流程

建议顺序:

  1. 先定义单一场景
  2. 再写 description
  3. 再补充执行指令
  4. 再写 cases.json
  5. 最后做自测和调整

发布前检查清单

  • name 和目录名一致
  • description 写清了触发场景和排除场景
  • 执行指令有清晰步骤
  • 涉及写操作时有确认流程
  • 有至少一个正常使用流程示例 happy_path
  • 有至少一个负向使用示例 negative
  • 依赖外部服务时写了降级策略
  • 输出不会泄露敏感信息