xiaozhi-skill-creator · diff

v2.1.7 to v2.1.8

1 added, 1 removed. Audit A to A.

---

name: xiaozhi-skill-creator

description: >

写一个新 SKILL 时用的编写工具：四层结构（角色/规则/记忆/输出）、安全与隐私边界、五步落地流程、常见问题诊断。

面向 SKILL 开发者与有编程/写提示词基础的高中生，在"我要新写一个学习类 SKILL""帮我把这个 SKILL 的规则写清楚""我的 SKILL 行为不稳定怎么排查""这个 SKILL 该记哪些字段"时使用。

它不替你写具体学科内容、不做学习辅导、不生成练习题；本仓库的词表与阈值一律以 shared/vocab.md 为准。

compatibility: WorkBuddy / SkillHub / OpenClaw / ClawHub

license: MIT

metadata:

display_name: 🛠️ SKILL 编写工具

- version: 2.1.7

+ version: 2.1.8

author: 小智伴学

category: 开发者工具

grade_bands:

- 高中

tags: [开发者工具, SKILL编写, 四层结构, 提示词工程, 元SKILL]

---

# 🛠️ SKILL 编写工具

> **定位：** 这是一个**开发者工具**，不是学生端学习 SKILL。

> 使用者是要**写一个新 SKILL 或改一个现有 SKILL** 的人——SKILL 开发者，或有编程、提示词基础、想自己动手做一个的高中生。

> 它教的是"怎么把一个 SKILL 写清楚"，不教任何学科内容。

> 技术边界：本工具不依赖任何平台运行时能力；它产出的是**文本规范**，具体 SKILL 依赖哪些能力，由那个 SKILL 自己按 `shared/platform-conventions.md` 声明。

### 写之前必读（本仓库的硬约束）

| 文件 | 作用 |

|---|---|

| `shared/vocab.md` | 全库唯一词表与阈值：错因四维、弱项五档、掌握度三档、置信度、授权位、提醒预算、学段 |

| `shared/platform-conventions.md` | 能力代号与统一降级路径、控制入口段落、提醒入队契约 |

| `shared/crisis-exception.md` | 危机例外三行片段与各类流程的接入点 |

| `shared/hint-ladder.md` | 提示阶梯（替代"永不给答案"的绝对禁令） |

| `shared/ai-item-check.md` | AI 出题自检协议 |

| `shared/grade-bands.md` | 学段参数表 |

| `SECURITY_BASELINE.md` | 安全与隐私基线 |

**任何新 SKILL 都不得自己另起一套词表、阈值或授权位。** 需要新词时改 vocab，不要在自己的 SKILL 里发明。

---

## 一、一个 SKILL 由什么构成

```

一个可用的 SKILL = frontmatter + 四层结构 + 边界声明 + 交接契约

frontmatter：顶层只写官方字段 name（等于目录名）/ description / license / compatibility；本库自有的 version / display_name / category / grade_bands / depends_on / tags 放进 `metadata:` 块

四层结构：角色层（它是谁）/ 规则层（它怎么做）/ 记忆层（它记什么）/ 输出层（它怎么回应）

边界声明：技术边界一行 + 控制入口段落 +（涉情绪时）危机例外三行

交接契约：只用 handover-protocol.schema.json 里已有的 handoverType 与字段

```

**description 的硬要求**：≤300 字；3-6 句带学科词的触发语；写明本 SKILL **不处理**什么、转给哪个 SKILL；不含"务必调用/必须激活"这类硬命令词，不含营销句和无出处的比例数字。

---

## 二、功能模块总览

```

SKILL 编写工具

├── 模块A 四层结构解析（理解篇）

├── 模块B 五步落地流程（操作篇）

├── 模块C 上下文与素材（进阶篇）

├── 模块D 八条编写实践（习惯篇）

└── 模块E 六项自检指标（诊断篇）

```

---

## 三、模块A：四层结构解析

每一个可用的 SKILL，都由以下**四层结构**驱动。

### 第一层：角色层（Role）——它是谁

```

定义SKILL的身份和职责边界。

这一层决定：AI 在这个 SKILL 里扮演什么角色、边界在哪。

✅ 好的角色层：

"你是一位面向中国初中生的数学学习教练，

负责按 shared/vocab.md §1 的通用四维记录并分析这位学生的数学错题，

不负责讲新课，也不负责发提醒。"

❌ 差的角色层：

"你是一个AI。"（太宽泛，没有边界）

"你是世界上最好的数学老师。"（虚浮，没有职责）

角色层写好的三个标准：

① 学段具体（初中生 / 小学高年级 / 初三备考生）

② 职责具体（建立错误档案 / 追问理解深度 / 管理词汇复习）

③ 功能边界清晰（只做什么，不做什么）

```

### 第二层：规则层（Rules）——它怎么做

```

定义具体的行为规则：什么情况下做什么，禁止什么。

规则层的三种写法：

① 触发-行为规则：

"当学生发来错题时，先追问学生的解题过程，不直接给答案。"

② 固定流程规则：

"每次分析完错误后，先征得同意，再把错误类型写入长期档案。"

③ 边界规则（**不要写成"永远不"式的绝对禁令**）：

"不在学生尝试之前给原题答案；提示按 shared/hint-ladder.md 逐级升，

到达本 SKILL 的默认最高级后，用同型例题或讲解 + 同类题收尾。"

✅ 好的规则层写法：

1. 先问"你已经尝试到哪一步"，再按提示阶梯给提示；默认最高级写明是 L4 还是 L6

2. 每次分析完错误后，生成待确认条目；用户确认且已授权时才写入长期档案

3. 弱项计数按 shared/vocab.md §5，由错题本唯一计数，本 SKILL 只接收事件

4. 语气温和而严谨，不做评判，只做分析和引导

5. 需要提醒时生成 reminder_enqueue 交给 IM 提醒，不自行承诺"我会在 X 时提醒你"

```

### 第三层：记忆层（Memory）——它记什么

```

定义应该积累的内容维度——决定这个 SKILL 能不能跨会话接上。

记忆层写的是：在用户授权后，持续存储哪些字段、落到 schema 的哪个位置。

✅ 具体的记忆层（好）：

对于每一道错题，记录：

· 学科和知识点标签

· 通用维度 basicDimension（概念模糊 / 计算失误 / 读题失误 / 方法用错，shared/vocab.md §1）

· 学科子类型 subtypeId（可选，如 B03 / P02 / G05 / RC01）

· 日期与 28 天窗口内累计次数

· 弱项状态（待处理 / 初步弱项 / 顽固弱项 / 突破中 / 已攻克，shared/vocab.md §4）

· 一句话根因

⚠️ 字段名与枚举**必须**取自 dna-profile.schema.json 与 handover-protocol.schema.json，

不要自己发明 camelCase 路径（如 studentAnalyzer.speakingLevel 这类是无效的）。

❌ 模糊的记忆层（差）：

"记住学生的情况。"（记什么？哪些？怎么存？）

记忆层写好的关键：

用"对于每一个[X]，记录：[具体字段列表]"的格式写清楚。

```

### 记忆层补充：安全边界必须写明

```

每个涉及长期记忆的 SKILL，都要写清五条：

1. 何时可以建立长期档案：用户明确同意后（授权位见 shared/vocab.md §8）

2. 何时只能用当前会话：未授权、暂停记忆、关闭共享时

3. 控制入口段落：直接复制 shared/platform-conventions.md 第四节六行，

"查看我的…""删除我的…"字样必须出现

4. 可共享给谁：仅限白名单内的 SKILL，且只共享最小必要字段

5. 给家长看的输出：先查 parentSharingConsent，含情绪内容再查 emotionSharingWithParent

```

### 记忆层补充：小学段与说话人确认

```

· ageBand 为小学各段时，consentGivenBy 必须包含"监护人"，否则不建档

· 学生与家长共用会话时，先问一句"现在是同学本人在吗"；

无法确认时进入受限模式：不读长期档案、不写记录、不执行删除、不变更授权位、

不输出家长版内容（不要写“默认按学生本人处理”）

```

### 第四层：输出层（Output）——它怎么回应

```

定义回应的格式、语气、长度，以及面对不同情况时的调整方式。

✅ 好的输出层：

"语气像一位认真负责但温和的数学私教老师，

肯定具体进步并精确指出问题。

分析错误时先整体后细节，每步写明轮次预算；

同一知识点同一维度 28 天内第 3 次出现时说：

'这不是偶然，是一个固定模式（哪三次、什么维度），我们专项突破它。'"

输出层的三个要素：

① 语气风格（温和/严格/鼓励型/苏格拉底型）

② 格式要求（长短、结构、是否需要特定格式）

③ 特殊情境响应（考前模式/学生焦虑时/多次出错时）

```

---

## 四、模块B：五步落地流程

### Step 1：明确SKILL的使用场景

```

创建SKILL之前，先回答三个问题：

① 这个SKILL在什么时候被用？

（每次做数学题时 / 每次学英语单词时 / 每次写作文时）

② 这个SKILL应该记住什么？

（错误类型 / 词汇掌握程度 / 写作弱项）

③ 这个 SKILL **不**做什么、该转给谁？

（不讲新课 → 转概念解释器；不记错题 → 转错题本；不发提醒 → 转 IM 提醒）

这一条要原样写进 description，用来消除与其他 SKILL 的触发冲突。

回答完这三个问题，四层结构就基本有了方向。

```

### Step 2：按四层结构填写提示词

**提示词模板（复制后修改【】内容即可）：**

```

你是一位专注于帮助【学段，如：中国初中生】【学科/任务】的AI教练。

你负责建立并维护这位学生的【档案/系统名称】。

《角色定义》

你是【一个具体角色】，只负责【职责】，不负责【明确排除的事】。

《核心规则》

1. 【触发-行为规则】

2. 【固定流程规则，每步写明轮次预算】

3. 【边界规则：提示按 shared/hint-ladder.md，默认最高级 L__】

4. 【退出规则：两轮无回复即收尾并归档】

5. 语气：【温和/严谨/追问式】

《安全与隐私边界》

1. 仅在用户明确同意后建立或读取长期档案；授权位见 shared/vocab.md §8。

2. 未获同意时，只使用当前会话信息，不创建跨会话记录。

3. 控制入口（复制 shared/platform-conventions.md 第四节六行，字样不可改）：

查看我的【X】/ 更正我的【X】/ 删除我的【X】/ 这次不要记忆 /

不要共享给其他SKILL / 导出我的【X】

4. 只向【白名单 SKILL】共享完成当前任务所需的最小字段摘要。

5. 需要提醒时生成 reminder_enqueue 交给 xiaozhi-im-reminder，不自行承诺提醒时间。

6. 给家长看的输出：先查 parentSharingConsent，含情绪内容再查 emotionSharingWithParent。

《危机例外》（涉及情绪文本的 SKILL 必须原样保留下面这段）

⚠️ 危机例外（最高优先级）：若对话中出现自伤/自残、轻生念头、遭受霸凌或伤害、持续严重绝望、家庭安全问题等超出学习范畴的信号，立即停止本 SKILL 的一切流程（含熔断、温情转化、数据展示、出题、家长摘要），按 shared/crisis-exception.md 处置：稳住不评判 → 说明 AI 边界 → 如实提示联系信任的成年人 → 按所在地区给出求助渠道（不确定地区时先问；中国大陆即时危险为 110/120，其他地区用当地紧急电话）。宁可误报，不可漏报；档案只记“已转介”的处置事实。

《记忆维度》

对于每一个【记录对象】，记录（字段名取自 dna-profile.schema.json）：

· 【字段1】

· 【字段2】

· 【字段3】

枚举一律用 shared/vocab.md 的取值，不自造。

《输出格式》

【语气风格、结构、轮次预算、特殊情境响应】

```

### Step 3：准备验证用的上下文素材

```

SKILL 写好后，用真实素材验证它是否按规则工作。

素材来源（由使用者自己整理成文字，不要求学生上传文件）：

· 一道真实错题的文字描述（题干 + 学生答案 + 正确答案 + 学生自述思路）

· 一段真实的对话片段（3-5 轮）

· 一个真实的知识点名称与所在章节

⚠️ 素材边界：

- 只用完成当前任务所需的最小信息；不收集真实姓名、学校班级全称、

联系方式、证件号、住址、家庭事件

- 用概括性描述替代精确身份信息

- 素材默认只在本次验证中使用，不进入长期档案；要长期保留必须单独征得同意

- 不要求上传 PDF、试卷扫描件、成绩单等文件——

收集文件带来不必要的隐私风险，对验证规则也没有帮助

```

### Step 4：用真实问题测试

```

不要问"你记住我了吗"——直接用真实的问题测试。

好的测试方式：

拿 Step 3 准备的素材跑一遍，逐条核对：

① 是否先追问解题过程，而不是直接给答案

② 通用四维定位是否用了 shared/vocab.md 的取值

③ 轮次是否落在写好的预算内，两轮无回复时是否收尾

④ 语气与输出结构是否符合输出层的设定

⑤ 涉及情绪时，危机例外是否先于熔断触发

任一条不符合预期，记录哪里不对，进入 Step 5。

```

### Step 5：迭代优化提示词

```

每个SKILL至少需要2-3轮迭代才能稳定。

常见问题和修复方向：

① 追问语气太呆板

→ 修改输出层：写明语气与句式偏好，给两三个正例

② 总是直接给答案，没走提示阶梯

→ 修改规则层：写明默认最高级（L4/L5/L6）与升级条件

③ 记录的信息不够用

→ 修改记忆层：对照 dna-profile.schema.json 补字段，不自造字段名

④ 输出结构不稳定

→ 修改输出层：把结构、轮次预算、每步产出写成硬要求

💡 迭代规律：先把四层都写完，再逐轮测试优化。

不要未经测试就大量使用，先用5-10次对话热身。

```

---

## 五、模块C：上下文与素材

### 三类可用来验证 SKILL 的素材

| 素材类型 | 具体形式 | 用来验证什么 |

|---------|---------|---------------|

| 一道真实错题 | 文字：题干 + 学生答案 + 正确答案 + 学生自述思路 | 四维定位、提示阶梯、轮次预算是否按规则走 |

| 一段真实对话 | 文字：3-5 轮的真实交互片段 | 语气、追问方式、退出规则是否生效 |

| 一个知识点 | 名称 + 所在章节 + 学段 | 学段判断、越纲标注、词表是否用对 |

### 三条素材纪律

```

纪律①：素材要真实但要脱敏

真实题目、真实思路 → 保留

真实姓名、学校班级、联系方式、家庭事件 → 一律不写进素材

纪律②：不要求上传文件

文字描述就足够验证规则是否生效。

不要在 SKILL 里写“请上传你的错题集 PDF”“发一份成绩单过来”这类要求。

纪律③：素材不等于长期档案

验证用的素材默认只在当次会话使用；

要长期保留必须单独征得同意，并按 shared/vocab.md §8 记录授权主体。

```

### 版权与来源

```

教辅原题、历年真题一律 copyrightStatus = 仅存索引（shared/vocab.md §11）：

只记“哪本书第几章第几题”，不整段复制原文。

自己改编的题标“改编”，公开可引用的标“公开可引用”。

```

---

## 六、模块D：八条编写实践

| 实践 | 核心规则 | 关键提示 |

|-----|---------|---------|

| ① description 写清边界 | 3-6 句带学科词的触发语 + 明确“不处理什么、转给谁” | 触发冲突大多是 description 写太宽造成的 |

| ② 词表只引用不定义 | 需要错因、状态、掌握度、置信度时，写“见 shared/vocab.md §N” | 各自造词是全库不一致的头号来源 |

| ③ 字段名对着 schema 抄 | 接口章节只写 dna-profile / handover 里真实存在的字段 | 虚构 camelCase 路径会被 CI 拦下 |

| ④ 交接只用已有类型 | 七种 handoverType 之外的一律不发明 | 新类型要先改 schema，不能在正文里假设 |

| ⑤ 每步写轮次预算 | “① 收信息（1 轮）② 定位（1 轮）……全流程 ≤ 6 轮” | 没有预算的流程会拖成十几轮 |

| ⑥ 给长流程配快速模式 | 一个动作 ≤ 2 轮能走完的简版 | 时间紧时学生会直接放弃长流程 |

| ⑦ 数字要有出处 | 经验参数写“经验值，约…”并允许用户调整 | 无出处的比例和倍数一律删 |

| ⑧ 高中内容要标注 | 越出义务教育课标的术语同行标 ⚠高中，或放“初高衔接”小节 | CI 会按关键词扫这一项 |

---

## 七、模块E：六项自检指标

**写完一个 SKILL 后，逐条自检：**

```

✅ 指标① 触发不冲突

description 里写明了不处理什么、转给谁；和相邻 SKILL 的触发语没有重叠

✅ 指标② 词表零自造

全文没有自定义的错因/状态/掌握度/置信度枚举，全部引用 shared/vocab.md

✅ 指标③ 字段可落地

接口章节里出现的每个字段名，都能在 dna-profile 或 handover schema 里找到

✅ 指标④ 边界齐全

技术边界一行 + 控制入口六行 +（涉情绪时）危机例外三行，都在

✅ 指标⑤ 流程有预算有出口

每步写了轮次，长流程有快速模式，有“两轮无回复即收尾”的退出

✅ 指标⑥ 学段说得清

frontmatter 的 grade_bands 与正文的适配说明一致；越纲内容有标注

```

**自检不过时的处理：**

```

指标①不过 → 重写 description：删营销句，补“不处理什么、转给谁”。

指标②不过 → 把自造的词替换成 vocab 的取值；确实缺词就先改 vocab。

指标③不过 → 打开 schema 逐个核对；查不到的字段要么删，要么先加 schema。

指标④不过 → 从 shared/platform-conventions.md 与 shared/crisis-exception.md 复制标准段落。

指标⑤不过 → 给每一步加“（N 轮）”，并补一个 ≤2 轮的快速模式。

指标⑥不过 → 对照 shared/grade-bands.md 第四节确认适用性，不适用就直接写“不适用”。

```

---

## 八、附录：常见编写误区

| 误区 | 表现 | 根本原因 | 修复方法 |

|-----|-----|---------|---------|

---

## 九、本工具在系统中的位置

```

SKILL 编写工具（开发者工具，不参与学生端运行时数据流）

──→ 产出：一份新的 SKILL.md 文本

←── 依据：shared/ 下的六份共享规范 + 两份 schema

⚠️ 本工具不读取任何学生档案、不发起交接、不写入 DNA。

它不在 handover-protocol 的 sender / recipient 枚举里，这是有意的。

```

---

## 十、参考资源

- `references/skill-templates-library.md` — 七个场景的 SKILL 提示词模板（每个模板头部固定带危机例外片段）

- `SECURITY_BASELINE.md` — 仓库级 SKILL 安全与隐私基线

- `shared/vocab.md` — 全库唯一词表与阈值

- `shared/platform-conventions.md` — 能力代号、降级路径、控制入口、提醒入队契约

- `shared/crisis-exception.md` — 危机例外三行片段

- `shared/hint-ladder.md` — 提示阶梯与默认最高级对照表

- `shared/ai-item-check.md` — AI 出题自检协议

- `shared/grade-bands.md` — 学段参数表

- `shared/dna-profile.schema.json` — 档案字段定义

- `shared/handover-protocol.schema.json` — 七种交接类型

---

> 💡 **写在最后：**

> 一个 SKILL 好不好用，不取决于它写得多长，

> 而取决于它的边界有多清楚——

> 它知道自己做什么、不做什么、什么时候该把人交给别人。