经验沉淀
技能沉淀（Skill Distiller）
目标：把一次性的任务过程，变成下一次能直接复用的技能。写完不算完，装进产品并真实用一次才算。
一、先判断值不值得沉淀
满足任意两条就写：
- 这个流程以后还会再做（同类需求 ≥ 2 次/月）。
- 过程中踩过坑，而文档里没写。
- 有非显然的关键判断（比如"先看发布时间再看版本号"）。
- 有重复三次以上的操作，可以脚本化。
- 交付物需要固定的验收标准。
不要沉淀：一次性的环境问题、纯查文档就能得到的知识、还没验证过的猜想。
二、按模板写
路径：skills/<name>/SKILL.md，脚本放 skills/<name>/scripts/。
---
name: <与目录名一致，小写连字符>
displayName: <中文短名，2-12 字，用户一眼看懂这是干什么的>
description: <一句话：解决什么问题 + 覆盖哪些坑>
whenToUse: <什么情况下加载>
---
# <标题>
## 结论先行
3 句话内说清：目标是什么、最容易走错的路线是什么、正确路线是什么。
## 关键事实
| 项 | 值 |
|---|---|
| 路径 / 版本 / 命令 | 实测值，不要写"大概" |
## 步骤
1. 命令（可直接复制）
2. 检查点：怎么知道这一步成功了
3. 失败时怎么办
## 坑（只写踩过的）
- 现象 → 原因 → 解法
## 验收清单
- [ ] 可观测的检查项
## 回滚
破坏性操作的还原步骤。
## 别做的事
几条硬禁忌。
写作要点：
- 命令必须是自己跑通过的，不要从文档抄。
- 检查点要可观测（退出码、文件存在、日志关键字、截图），不要写"确认没问题"。
- 一个技能只解决一类问题；超过 150 行就拆成两个。
- 术语跟产品保持一致（三山开物 / DSH / 运行时 / profile）。
三、命名规范
每个技能有两个名字，缺一不可。
name（给机器和目录用）
- 小写连字符：
kaiwu-runtime-audit、electron-asar-inspect。 - 前缀表达领域：
kaiwu-（三山开物产品）、dsh-（底层框架）、win-（Windows 环境）。 - 名字是"做什么"，不是"关于什么"：
electron-asar-inspect✅，asar-knowledge❌。
displayName（给人看）
- 2-12 个汉字，短、直白，像一个按钮上的字：
代码评审、经验沉淀、运行时体检。 - 要能直接填进"How do I…"这一句：用户问「这个技能是干嘛的」，看名字就能答上来。
- 不用英文 slug、不堆术语、不写长句：
dev-code-review❌，五轴正确性可读性架构安全性能评审❌。 - 确实绕不开的专有名词可以保留：
Electron 包检查、Git 提交规范。 - 同类技能名字要成体系，别一个叫「体检」一个叫「检查版本」。
validate会检查长度和 slug 误用。
四、校验 + 安装（必做）
node scripts/skills.mjs validate # frontmatter、目录名、引用脚本是否存在
node scripts/skills.mjs install # 同步到 %APPDATA%\三山开物\dsh-home\skills
node scripts/skills.mjs list # 确认已安装且 hash 一致
检查点：list 里该技能显示 installed 且 hash 匹配。没装上就等于没沉淀。
五、发布到公司仓库
node scripts/skills.mjs publish
第一次需要先配 remote：
git init
git remote add origin <公司仓库地址>
发布前自查：
- [ ] 技能里没有本机专用路径（除必要的安装路径外）
- [ ] 没有密钥、token、内网口令
- [ ] 引用的脚本都在
scripts/里，且validate通过 - [ ] 至少被真实任务用过一次
六、维护
- 用出问题就改，改完重新
validate+install。 - 连续三次使用都稳定，才值得写进对外文档。
- 技能之间不要互相复制大段内容，抽公共脚本。
别做的事
- 别写流水账（"我先看了 A，又看了 B"）——只留可复用的判断和命令。
- 别把没验证过的步骤写进去，尤其是"应该可以"。
- 别把技能写成产品说明书；说明书放
docs/。 - 别在技能里放密钥、证书、内网地址。