Skill 编写纪律（skill-authoring-discipline）
Adapted from HKUDS/nanobot (MIT)，nanobot/skills/skill-creator。原 skill 深度绑定 nanobot 平台的 init/package 脚本；本版剥离平台专有流程，把其编写方法论重写为任何 Agent 平台通用的自包含中文纪律，并附一个纯标准库 frontmatter 校验脚本 scripts/validate_frontmatter.py（零依赖、无需密钥）。
0. 核心前提：上下文是公共财
技能与系统提示词、对话历史、其他技能的元数据、用户请求共享同一个上下文窗口。写技能不是写文档，是给一个已经很聪明的模型写"入职指南"：
- 默认假设执行者已经懂通识。只写它不具备的程序性知识、领域约定、易错细节。
- 每一段都过两道闸：「执行者真的需要这段解释吗？」、「这段配得上它的 token 成本吗？」。过不了就删。
- 用紧凑示例替代冗长解释。一个对比例子胜过三段描述。
1. 自由度匹配：窄桥加护栏，旷野多走路
指令的松紧度必须匹配任务的脆弱度与一致性要求，不是越具体越好：
| 自由度 | 形式 | 适用场景 |
|---|---|---|
| 高 | 文字指引 | 多种做法都成立、决策依赖上下文、靠启发式即可 |
| 中 | 带参数的伪代码/脚本 | 有首选模式但允许变体、配置影响行为 |
| 低 | 固定脚本、少参数 | 操作脆弱易错、一致性关键、步骤顺序不可乱 |
判断口诀：任务是窄桥（一步踏错就坠落）→ 上低自由度护栏；是旷野（多条路都能到）→ 高自由度放行。
2. 解剖结构：一个 SKILL.md + 三类资源
skill-name/
├── SKILL.md # 必需：frontmatter（元数据）+ 正文（触发后才加载的指令）
├── scripts/ # 可执行代码：需要确定性或被反复重写的任务
├── references/ # 参考文档：执行中按需载入上下文的资料
└── assets/ # 资产：不进上下文、直接进产出的文件
三类资源的职责边界：
- scripts/：同一代码被反复重写、或需要确定性可靠性时收进来。优点是省 token、结果确定、可不读入上下文直接执行。注意：执行者仍可能读它来打补丁或做环境适配，所以要写得可读。
- references/：数据库模式、API 文档、领域知识、政策、详细工作流。优点是保持 SKILL.md 精瘦、按需加载。超过 1 万词的参考文件，要在 SKILL.md 里给出检索关键词（grep 模式），让执行者能定位而非通读。
- assets/：模板、图标、字体、样板代码等产出用文件。关键区别：用于产出，不用于阅读。
3. 渐进披露：三级加载
- 元数据（name + description）：永远在上下文里，约百词以内。
- SKILL.md 正文：技能触发后才加载。控制在 500 行内。
- 捆绑资源：由执行者按需加载。脚本可不进上下文，故实际无上限。
接近 500 行就拆分。拆分出的文件必须在 SKILL.md 中显式引用并说明何时读它——存在但没人知道，等于不存在。
三种拆分模式：
- 模式一（高层指南 + 引用）：正文给快速上手，高级特性、API 参考、示例各拆一个文件，按需读。
- 模式二（按域组织）：技能覆盖多个领域/框架时，正文只留导航，每域一个文件；用户问到哪个域就读哪个，无关域零加载。
- 模式三（条件细节）：正文给常规路径，边缘场景（如批注处理、特定格式）链接到专门文件。
嵌套铁律：引用只许一层深——所有参考文件直接从 SKILL.md 链出，不允许 A 引 B、B 引 C 的套娃；超过 100 行的参考文件顶部要有目录。
4. description 是唯一触发器
执行者只读 frontmatter 的 name 和 description 来决定何时用你的技能——正文里写"何时使用本技能"章节是无效的，因为正文在触发之后才被加载。因此：
- description 必须同时包含做什么与什么时候用（具体触发语境、触发短语、排除场景）。
- "何时使用"的全部信息放进 frontmatter，正文不再重复。
- frontmatter 保持最小化：不加用不上的额外字段。
5. 命名规则
- 只用小写字母、数字、连字符；文件夹名与技能名完全一致。
- 64 字符以内；优先简短的动词短语（描述动作而非名词堆砌）。
- 能提升触发清晰度时按工具加命名空间（如
gh-address-comments）。
6. 禁止事项
- 禁止冗余文件：不写 README、INSTALLATION_GUIDE、QUICK_REFERENCE、CHANGELOG 之类的外围文档。技能只包含让执行者完成工作所需的信息，创建过程、安装步骤、用户文档一律不进。
- 禁止内容双写：同一信息只活在 SKILL.md 或 references 之一，不得两处都有（漂移的开始）。
- 禁止占位残留：模板生成的占位文件、示例文件用不上就删，只保留实际需要的资源目录。
7. 六步创建流程
- 用例理解：先收集具体使用示例（"用户会说什么来触发它？"），跳过此步仅当用法已明确。
- 资源规划：逐例分析"每次执行都要重做什么"——重写的代码收进 scripts，重查的资料收进 references，重用的样板收进 assets。
- 初始化：按平台规范建目录骨架。
- 编辑：先实现资源，再写正文；全文用祈使句；新加的脚本必须实际运行验证（同类多个时抽代表性样本测）。
- 打包/校验：跑平台校验（frontmatter 格式、命名、目录结构、description 质量、资源引用），不过就修，修完再校。
- 迭代：真实使用 → 发现卡顿 → 定位该改正文还是资源 → 修改后再测。技能是活的，第一版不是终版。
8. 快速自检
发布前问五个问题：
- 删掉任何一段，执行者会变笨吗？不会的段还在吗？
- 任务的窄桥与旷野分清了吗？护栏加在窄桥上了吗？
- 三个"何时用"的场景写进 description 了吗？
- 有没有 README/CHANGELOG 之类的冗余文件混进来了？
- scripts 里的每个脚本都实际跑过吗？
配套脚本 scripts/validate_frontmatter.py <skill目录>：校验 frontmatter 必填字段、名称与目录一致、description 触发信息充分性提示，零依赖。
