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