SKILL 编写工具

SKILL.md

---
name: xiaozhi-skill-creator
description: '写一个新 SKILL 时用的编写工具：四层结构（角色/规则/记忆/输出）、安全与隐私边界、五步落地流程、常见问题诊断。面向 SKILL 开发者与有编程/写提示词基础的高中生，在"我要新写一个学习类 SKILL""帮我把这个 SKILL 的规则写清楚""我的 SKILL 行为不稳定怎么排查""这个 SKILL 该记哪些字段"时使用。它不替你写具体学科内容、不做学习辅导、不生成练习题；本仓库的词表与阈值一律以 shared/vocab.md 为准。'
compatibility: WorkBuddy / SkillHub / OpenClaw / ClawHub
license: MIT
display_name: 🛠️ SKILL 编写工具
version: 2.11.2
author: 小智伴学
category: 开发者工具
grade_bands:
  - 高中
tags: [开发者工具, SKILL编写, 四层结构, 提示词工程, 元SKILL]
slug: xiaozhi-skill-creator
displayName: 🛠️ SKILL 编写工具
summary: '写一个新 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 抢触发 | 角色层没限定职责 | 写出“只负责XX，不负责YY，YY 转给 zzz” |
| 规则太少 | 行为不稳定，时好时差 | 规则层只有 1-2 条 | 补到至少 4-6 条，含边界规则与退出规则 |
| 记忆太模糊 | 记了但不知道记了什么，也写不进 schema | 记忆层没有具体字段 | 改用“对于每个X，记录：[schema 里的字段名]” |
| 自造词表 | 同一个概念全库三种叫法 | 觉得自己的说法更顺口 | 一律引用 shared/vocab.md，需要新词就先改 vocab |
| 绝对禁令 | 写“永远不给答案”，把学生困死 | 把“不代做”误解成“不能讲” | 改写为提示阶梯 + 写明默认最高级 |
| 越权承诺 | 自己说“我明天提醒你”、自己按月出月报 | 没区分“入队”和“发送” | 提醒走 reminder_enqueue；周期报告改成用户请求后生成 |

---

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

```
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 好不好用，不取决于它写得多长，
> 而取决于它的边界有多清楚——
> 它知道自己做什么、不做什么、什么时候该把人交给别人。