writing-skill：把经验写成可移植的 skill

遵循 goal-first：先指出要纠正的实际行为及其成本，再做最小规则修改。能修现有条款就不新增重叠 skill；公共原则只维护一处，入口保留短指引。技能使用应比临时摸索省事，不能把方法论变成额外的报告、审批和必跑矩阵。

改动前确认维护归属：只修改自维护技能；grilling、diagnosing-bugs 等第三方上游技能不直接打补丁或覆盖共享副本。保留其方法价值和更新能力；个人差异放自有入口的触发、分工与适用范围。实验矩阵按研究目的判断，探索、消融、Pareto 和论文覆盖不是过度设计。

1. 先判定：这内容配不配做 skill

项目结果/经验成库先用distill-project-kb找证据、判断价值并让用户补漏确认；已有领域流程完成同等工作时直接复用，不重复筛选。本skill负责skill载体的编写与组织，不替代领域入库规范。知识库可保存带条件的案例事实，不限于纠正行为的指令；skill是使用入口，不是深度上限。

混了本机事实的通用方法 → 写成 skill 时占位符化（{{路径}}），本机值进 host 层或记忆；platform-environment-skill-audit 管回流的脱敏底线。

2. 定形（写之前想清楚）

• 命名：kebab-case，动词或名词短语，≤64 字符，目录名=name；前缀可对齐家族（exp-、accel-）。
• 放哪：主体维护的正文放base/research/accel/kb对应组；只此一机放~/.agents/skills/。独立领域项目在自己的源仓维护，即使同一作者也不收编副本。
• 如何接外部：区分套件代装依赖、可选集成和只引用资源。只有明确由setup管理的外部skill才在skills-external.sh登记来源/精确名；按需自行安装的领域库只给入口、用途与缺失处理，不自动代装或接管更新。安装副本与来源快照不是第二维护源。
• 分工：与相邻 skill 的边界一句话写进 description（"装环境用 X，写代码用本 skill"），避免双触发或都不触发。
• 演化性质：写时定档，明确更新约定。

安装策略：演化型可覆盖刷新；冻结型只装一次。

3. description（决定生死的字段）

• 第三人称或祈使，what + when + 触发词：做什么、什么时候用、用户会怎么说到它（含中文口语触发词）。
• 只写触发所需，不写实现细节；≤1024 字符。
• 反例："处理文件"（不命中任何话术）；正例："Extract text and tables from PDF files. Use when working with PDF files or when the user mentions PDFs, forms"。

4. 正文（高熵、直白、引导强）

• 上限 ~150 行；只留影响执行的信息；不为凑行数把多个要点挤成一行。
• steps 与 reference 分开：步骤内联在 SKILL.md；查表类、只有部分分支才需要的推到同目录附属文件，指针只一层深。
• 每步有完成判据：这步做完的标志是什么（可观察的输出/状态），没有判据的步骤是废话步骤。
• 自由度按脆弱性给：易错处给精确命令（照抄可跑），判断处给启发式一句话；不要给菜单让 agent 自己挑。
• 细节=差异点：确切命令、键名、版本行、真实踩过的坑（症状→原因→处置）；删常识、铺垫、重复解释，保留影响判断的条件、原因、例外。
• leading words：同一概念在三处重复叙述 → 收敛成一个引导词；每个多余句子都是下次维护的债。
• 时效内容带日期（版本行、矩阵），未验证的标 (未验证)；不写死会过期的结论而不给重查命令。
• 中文为主，遵循 readable-docs：短语优先、完整句按需、段落作例外；列表一项一意，对比表单元格只写差异。

5. 收尾检查（写完自查）

1. 触发测试：拿 2–3 句真实用户话术模拟，description 会不会命中？相邻 skill 会不会抢？
2. 信息与扫读检查：还能删哪些字而不丢含义？检查最长条目，拆开独立要点；不按解释与代码的长度比删内容。
3. 去情境化检查：grep 本机痕迹（用户名/主机路径/IP），该占位符的占位符。
4. 首次真用：skill 的价值在第二次被触发时验证；用歪了改 description，用漏了补触发词，别预先设计用不到的分支（YAGNI）。

6. 演化

固定回路：真机改本机副本 → 下载到开发机 → 合入仓库 push → 各机拉新版。

• 落点：最小修改回到 skill 本体，不改结构；规则被推翻时更新对应小节并注明证据。
• 刷新：覆盖刷新组自动；只装一次组显式重装。
• 防丢：本机修改未回流前，别重跑 setup 的覆盖刷新。