writing-skills · Skill 写作指南
编写与审校 skill 文档的方法论 skill：核心观点是"写作 skill 就是把 TDD 应用于流程文档"——先用无 skill 的基线场景看智能体如何失败（红），再针对性写 SKILL.md（绿），最后寻找漏洞堵住（重构）。
内置 SKILL.md 结构规范、skill 类型划分（技巧/模式/参考）与 SDO 描述优化原则（description 只写"何时使用"，不写流程总结），让写出的 skill 既可被发现、又真正改变智能体行为。
调用示例：在聊天框中说"我想把这套代码审查流程写成一个 skill"。
产品详解
定位
writing-skills 是写作 skill 文档的指南 skill：核心原则是——没看过智能体在无 skill 下失败，就不知道文档该教什么。它回答"文档怎么写"，不负责实测与打包。
核心能力
- TDD 映射：测试用例 = 子智能体压力场景；生产代码 = SKILL.md；红 = 无 skill 时智能体违规；绿 = 有 skill 时合规；重构 = 堵漏洞。先写测试（跑基线场景），再写文档。
- 何时创建 skill 的判断清单：创建——技巧不直观、会反复引用、模式通用；不创建——一次性方案、已有完善文档、可用正则强制的机械约束（那种直接自动化）。
- Skill 类型划分：Technique（具体方法，有步骤）、Pattern（思维方式）、Reference（API/语法参考）。
- SKILL.md 结构模板：frontmatter（name/description 必填）+ Overview、When to Use、Core Pattern、Quick Reference、Common Mistakes 等；目录扁平化，重型参考拆独立文件。
- SDO（Skill 发现优化）：description 只写"何时使用"（以 Use when 开头），不写技能流程总结——描述决定未来智能体是否会加载这个 skill。
工作流程
- 跑基线压力场景，看智能体如何失败，记录其借口与违规
- 针对这些具体违规写 SKILL.md（最小化、解释 why 而非堆 MUST）
- 复测验证智能体合规
- 寻找新的漏洞/借口，堵住，重测
输入与输出
| 输入 | 说明 |
|---|---|
| 想沉淀的技巧/模式/参考资料 | 必填 |
| 已知的失败场景 | 选填 |
输出：符合结构规范的 SKILL.md 草稿。
与相邻 skill 的区别
- skill-creator：把 skill 做出来并验证有效的完整工具链——并行实测、量化基准、人工评审、触发率优化、打包发布。
- writing-skills（本）：写 skill 文档的方法论——TDD 写文档、SKILL.md 结构、SDO 原则。两者常配合：用本 skill 写好文档，用 skill-creator 验证它有效。
适用场景
- 把个人经验沉淀为可复用的 skill
- 审校已有 skill 文档是否符合结构规范
- 写新 skill 前先确定文档结构与类型
使用前准备
- 无特殊配置。官方建议先掌握 TDD 的 RED-GREEN-REFACTOR 周期（这是本 skill 的理论前提）。
writing-skills 隶属于 Aiglade Skill 库。在 Aiglade 聊天框中用自然语言描述需求即可调用。