SKILL 编写工具

写一个新 SKILL 时用的编写工具：四层结构（角色/规则/记忆/输出）、安全与隐私边界、五步落地流程、常见问题诊断。面向 SKILL 开发者与有编程/写提示词基础的高中生，在"我要新写一个学习类 SKILL""帮我把这个 SKILL 的规则写清楚""我的 SKILL 行为不稳定怎么排查""这个 SKILL 该记哪些字段"时使用。它不替你写具体学科内容、不做学习辅导、不生成练习题；本仓库的词表与阈值一律以 shared/vocab.md 为准。

小智伴学@qizhitang

Install

openclaw skills install @qizhitang/xiaozhi-skill-creator

🛠️ 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 由什么构成

text

一个可用的 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；不含"务必调用/必须激活"这类硬命令词，不含营销句和无出处的比例数字。

二、功能模块总览

text

SKILL 编写工具
├── 模块A  四层结构解析（理解篇）
├── 模块B  五步落地流程（操作篇）
├── 模块C  上下文与素材（进阶篇）
├── 模块D  八条编写实践（习惯篇）
└── 模块E  六项自检指标（诊断篇）

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

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

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

text

定义SKILL的身份和职责边界。
这一层决定：AI 在这个 SKILL 里扮演什么角色、边界在哪。

✅ 好的角色层：
"你是一位面向中国初中生的数学学习教练，
 负责按 shared/vocab.md §1 的通用四维记录并分析这位学生的数学错题，
 不负责讲新课，也不负责发提醒。"

❌ 差的角色层：
"你是一个AI。"（太宽泛，没有边界）
"你是世界上最好的数学老师。"（虚浮，没有职责）

角色层写好的三个标准：
① 学段具体（初中生 / 小学高年级 / 初三备考生）
② 职责具体（建立错误档案 / 追问理解深度 / 管理词汇复习）
③ 功能边界清晰（只做什么，不做什么）

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

text

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

规则层的三种写法：

① 触发-行为规则：
"当学生发来错题时，先追问学生的解题过程，不直接给答案。"

② 固定流程规则：
"每次分析完错误后，先征得同意，再把错误类型写入长期档案。"

③ 边界规则（**不要写成"永远不"式的绝对禁令**）：
"不在学生尝试之前给原题答案；提示按 shared/hint-ladder.md 逐级升，
 到达本 SKILL 的默认最高级后，用同型例题或讲解 + 同类题收尾。"

✅ 好的规则层写法：
1. 先问"你已经尝试到哪一步"，再按提示阶梯给提示；默认最高级写明是 L4 还是 L6
2. 每次分析完错误后，生成待确认条目；用户确认且已授权时才写入长期档案
3. 弱项计数按 shared/vocab.md §5，由错题本唯一计数，本 SKILL 只接收事件
4. 语气温和而严谨，不做评判，只做分析和引导
5. 需要提醒时生成 reminder_enqueue 交给 IM 提醒，不自行承诺"我会在 X 时提醒你"

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

text

定义应该积累的内容维度——决定这个 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]，记录：[具体字段列表]"的格式写清楚。

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

text

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

1. 何时可以建立长期档案：用户明确同意后（授权位见 shared/vocab.md §8）
2. 何时只能用当前会话：未授权、暂停记忆、关闭共享时
3. 控制入口段落：直接复制 shared/platform-conventions.md 第四节六行，
   "查看我的…""删除我的…"字样必须出现
4. 可共享给谁：仅限白名单内的 SKILL，且只共享最小必要字段
5. 给家长看的输出：先查 parentSharingConsent，含情绪内容再查 emotionSharingWithParent

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

text

· ageBand 为小学各段时，consentGivenBy 必须包含"监护人"，否则不建档
· 学生与家长共用会话时，先问一句"现在是同学本人在吗"；
  无法确认时进入受限模式：不读长期档案、不写记录、不执行删除、不变更授权位、
  不输出家长版内容（不要写“默认按学生本人处理”）

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

text

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

✅ 好的输出层：
"语气像一位认真负责但温和的数学私教老师，
 肯定具体进步并精确指出问题。
 分析错误时先整体后细节，每步写明轮次预算；
 同一知识点同一维度 28 天内第 3 次出现时说：
 '这不是偶然，是一个固定模式（哪三次、什么维度），我们专项突破它。'"

输出层的三个要素：
① 语气风格（温和/严格/鼓励型/苏格拉底型）
② 格式要求（长短、结构、是否需要特定格式）
③ 特殊情境响应（考前模式/学生焦虑时/多次出错时）

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

Step 1：明确SKILL的使用场景

text

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

① 这个SKILL在什么时候被用？
   （每次做数学题时 / 每次学英语单词时 / 每次写作文时）

② 这个SKILL应该记住什么？
   （错误类型 / 词汇掌握程度 / 写作弱项）

③ 这个 SKILL **不**做什么、该转给谁？
   （不讲新课 → 转概念解释器；不记错题 → 转错题本；不发提醒 → 转 IM 提醒）
   这一条要原样写进 description，用来消除与其他 SKILL 的触发冲突。

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

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

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

text

你是一位专注于帮助【学段，如：中国初中生】【学科/任务】的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：准备验证用的上下文素材

text

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

素材来源（由使用者自己整理成文字，不要求学生上传文件）：
· 一道真实错题的文字描述（题干 + 学生答案 + 正确答案 + 学生自述思路）
· 一段真实的对话片段（3-5 轮）
· 一个真实的知识点名称与所在章节

⚠️ 素材边界：
- 只用完成当前任务所需的最小信息；不收集真实姓名、学校班级全称、
  联系方式、证件号、住址、家庭事件
- 用概括性描述替代精确身份信息
- 素材默认只在本次验证中使用，不进入长期档案；要长期保留必须单独征得同意
- 不要求上传 PDF、试卷扫描件、成绩单等文件——
  收集文件带来不必要的隐私风险，对验证规则也没有帮助

Step 4：用真实问题测试

text

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

好的测试方式：
拿 Step 3 准备的素材跑一遍，逐条核对：
① 是否先追问解题过程，而不是直接给答案
② 通用四维定位是否用了 shared/vocab.md 的取值
③ 轮次是否落在写好的预算内，两轮无回复时是否收尾
④ 语气与输出结构是否符合输出层的设定
⑤ 涉及情绪时，危机例外是否先于熔断触发

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

Step 5：迭代优化提示词

text

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

常见问题和修复方向：

① 追问语气太呆板
   → 修改输出层：写明语气与句式偏好，给两三个正例

② 总是直接给答案，没走提示阶梯
   → 修改规则层：写明默认最高级（L4/L5/L6）与升级条件

③ 记录的信息不够用
   → 修改记忆层：对照 dna-profile.schema.json 补字段，不自造字段名

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

💡 迭代规律：先把四层都写完，再逐轮测试优化。
   不要未经测试就大量使用，先用5-10次对话热身。

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

三类可用来验证 SKILL 的素材

素材类型	具体形式	用来验证什么
一道真实错题	文字：题干 + 学生答案 + 正确答案 + 学生自述思路	四维定位、提示阶梯、轮次预算是否按规则走
一段真实对话	文字：3-5 轮的真实交互片段	语气、追问方式、退出规则是否生效
一个知识点	名称 + 所在章节 + 学段	学段判断、越纲标注、词表是否用对

三条素材纪律

text

纪律①：素材要真实但要脱敏
  真实题目、真实思路 → 保留
  真实姓名、学校班级、联系方式、家庭事件 → 一律不写进素材

纪律②：不要求上传文件
  文字描述就足够验证规则是否生效。
  不要在 SKILL 里写“请上传你的错题集 PDF”“发一份成绩单过来”这类要求。

纪律③：素材不等于长期档案
  验证用的素材默认只在当次会话使用；
  要长期保留必须单独征得同意，并按 shared/vocab.md §8 记录授权主体。

版权与来源

text

教辅原题、历年真题一律 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 后，逐条自检：

text

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

✅ 指标②  词表零自造
   全文没有自定义的错因/状态/掌握度/置信度枚举，全部引用 shared/vocab.md

✅ 指标③  字段可落地
   接口章节里出现的每个字段名，都能在 dna-profile 或 handover schema 里找到

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

✅ 指标⑤  流程有预算有出口
   每步写了轮次，长流程有快速模式，有“两轮无回复即收尾”的退出

✅ 指标⑥  学段说得清
   frontmatter 的 grade_bands 与正文的适配说明一致；越纲内容有标注

自检不过时的处理：

text

指标①不过 → 重写 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；周期报告改成用户请求后生成

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

text

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

SKILL 编写工具

Install

🛠️ SKILL 编写工具

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

一、一个 SKILL 由什么构成

二、功能模块总览

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

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

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

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

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

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

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

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

Step 1：明确SKILL的使用场景

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

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

Step 4：用真实问题测试

Step 5：迭代优化提示词

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

三类可用来验证 SKILL 的素材

三条素材纪律

版权与来源

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

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

八、附录：常见编写误区

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

十、参考资源

Related skills