DuMate Skill 开发指南
更新时间:2026-07-17
本文说明 DuMate Skill 的结构、编写方式、测试方法和安全要求,供开发者参考。
适用对象
- 想为 DuMate 创建新 Skill 的开发者
- 需要调整触发词、执行流程或测试用例的开发者
- 需要接入工具或外部服务的开发者
最小结构
最小结构如下:
Text
1daily-summary/
2├── SKILL.md
3└── tests/
4 └── cases.json
可选目录如下:
scripts/:存放确定性脚本,例如数据处理、接口调用references/:存放静态参考资料,例如长文档、API 说明、业务规则assets/:存放图标、模板和其他静态资源
编写 SKILL.md
SKILL.md 是 Skill 的核心,它同时承担“入口说明”和“执行指令”两种角色。
先写 name 和 description
name建议用kebab-case,例如daily-summary,并与文件夹名保持一致。description决定这个 Skill 是否会被正确触发。
推荐公式:
YAML
1description: |
2 [一句话说明这个 Skill 做什么]。
3 Use when user says "[常见说法1]", "[常见说法2]", "[常见说法3]".
4 不触发:[容易混淆但不属于本 Skill 的场景]。
写法原则:
- 使用用户真实会说的话,不用内部术语
- 覆盖正式说法和口语说法
- 明确写出不该触发的场景
示例:
YAML
1description: |
2 从已有联系人中搜索信息,并返回联系方式和最近互动记录。
3 Use when user says "查一下这个客户", "CRM 里有没有这个人", "找找某公司的联系方式".
4 不触发:新增联系人、编辑客户信息、查询公开公司信息。
元数据示例
YAML
1---
2name: daily-summary
3description: |
4 根据用户提供的当天经历,生成简洁的每日总结。
5 Use when user says "今天总结一下", "帮我记录今天", "日记", "今日回顾".
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---
说明:不同版本的元数据字段可能略有差异,发布前请以平台校验提示为准。
写 Instructions
Instructions 负责定义 Skill 触发后怎么做。建议用清晰的步骤写法,避免模糊表达。
推荐结构:
Markdown
1## Instructions
2
3### 步骤 1 - 信息确认
4如果缺少必要信息,先向用户追问。
5
6### 步骤 2 - 执行任务
7按既定格式完成输出。
8
9### 步骤 3 - 执行前确认
10如果涉及向外部系统发送内容、删除数据、写入记录或修改已有数据,先展示完整内容并等待用户确认。
11
12### 输出格式
13明确说明最终结果应该长什么样。
编写建议:
- 用祈使句,直接告诉模型要做什么
- 能并行的步骤分开写
- 向外部系统写入或执行不可逆操作时,必须写确认
- 需要引用外部资料时,说明从哪里读、怎么用
写好降级策略
如果 Skill 依赖外部工具或外部服务,就要提前写好降级逻辑。
常见的三种方式:
| 类型 | 适用场景 | 处理方式 |
|---|---|---|
degrade |
可用替代方案完成任务 | 改用基础能力继续输出 |
partial |
只能拿到部分数据 | 说明缺失内容并返回已有结果 |
block |
写入、发送、删除、鉴权失败 | 明确停止并提示用户处理后重试 |
处理规则:
- 能替代就降级
- 只能部分完成就部分返回
- 有风险的写操作就停止
给出例子
至少提供 1 个完整示例,建议覆盖主流程和边界情况。
Markdown
1## Examples
2
3**用户**:帮我总结一下今天,上午开了产品评审会,下午和客户聊了需求。
4
5**DuMate**:
6**2026-06-01 每日总结**
71. 今日要点:产品评审会 / 客户需求沟通
82. 感受与收获:今天推进了两个重要事项,值得整理后续跟进内容
93. 明日计划:如有待办,可继续补充
编写 tests/cases.json
cases.json 用来验证两个问题:
- 这个 Skill 该不该触发
- 触发后做得对不对
推荐结构如下:
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}
建议每个 Skill 至少包含:
happy_pathnegative
如果涉及写操作,再补上:
- 用户确认后执行
- 用户拒绝时不执行
如果依赖外部工具,再补上:
- 工具可用时的增强路径
- 工具不可用时的降级路径
常用断言字段:
| 字段 | 说明 |
|---|---|
trigger_skill |
是否应该触发当前 Skill |
output_contains |
输出中应包含的关键词 |
asks_clarification |
是否需要追问缺失信息 |
connected_tools |
模拟已连接的工具或服务 |
calls_tool |
期望调用的工具 |
does_not_call |
不应调用的工具 |
uses_fallback |
是否进入降级逻辑 |
fallback_type |
降级类型,例如degrade、partial、block |
工具接入与复杂流程
当 Skill 只需要生成文本时,尽量保持简单。
如果需要调用外部服务,建议把稳定、重复、易出错的部分封装成脚本,再在 Instructions 里说明调用顺序。
什么时候写脚本
- 需要确定性输出
- 操作有副作用
- 处理顺序不能错
- 逻辑太长,模型容易写偏
什么时候保持自然语言
- 只要阅读和总结
- 只要轻量判断
- 结果不依赖精确流程
分级参考
| 级别 | 特点 |
|---|---|
| L0 | 只靠模型本身完成 |
| L1 | 结合基础工具,例如搜索、文件处理 |
| L2 | 需要调用外部服务 |
| L3 | 基础工具和外部服务都要用 |
安全与合规
发布时,优先保证可验证、可回退、最小权限。
原则:
- 只处理完成任务必须的数据
- 不要暴露密码、Token、密钥等敏感信息
- 向外部系统写入或执行不可逆操作时先确认
- 不要虚构来源、结果或执行记录
- 涉及隐私、财务、医疗等内容时要更谨慎
如果外部服务不可用,宁可明确说明,也不要编造结果。
如果需要外部授权,请使用平台提供的标准凭证方案,不要在 Skill 指令、示例或错误提示中暴露密钥、凭证路径或其他敏感实现细节。
开发流程
建议顺序:
- 先定义单一场景
- 再写
description - 再补
Instructions - 再写
cases.json - 最后做自测和调整
发布前检查清单
name和目录名一致description写清了触发场景和排除场景Instructions有清晰步骤- 涉及写操作时有确认流程
- 有至少一个
happy_path - 有至少一个
negative - 依赖外部服务时写了降级策略
- 输出不会泄露敏感信息
评价此篇文章
