--- 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.11.1 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 抢触发 | 角色层没限定职责 | 写出“只负责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 好不好用，不取决于它写得多长， > 而取决于它的边界有多清楚—— > 它知道自己做什么、不做什么、什么时候该把人交给别人。