用途
add-skill 用于在本仓库中编写或改进一个生产质量的 Agent Skill，采用 eval-first（评估优先）工作流。它一次只构建一个技能，放在 skills/<name>/ 目录下。开始前每个会话应阅读一次 docs/skill-authoring.md 和 docs/evals.md，这两份文档是该工作流执行的规则手册。若以 /add-skill <args> 形式调用，则将 $ARGUMENTS 视为第 1 步中要界定范围的技能名称或想法。
不适用场景
- 创建新的技能仓库：这发生在本仓库之上的工作区中。
- 基础设施工作（hooks、CI、validator、docs）：属于普通编辑，按 PR 级别审查。
- 仅仅重复模型已经做得很好之事的“技能”：不要构建；技能必须修复一个具体观察到的失败。
工作流
-
界定范围。用一句话说明该技能做什么以及它修复的具体失败。如果这句话需要“和”，就拆分为多个技能并一次做一个。检查 skills/ 和 README 目录是否有重叠——相邻描述会互相抢触发；调整范围或规划不重叠的措辞。
-
收集资料。递归阅读 .local/——每个子文件夹和文件都是素材（研究、示例、约束）。然后在其之外做研究：对主题进行网络搜索以获取当前事实、官方文档和先例；对任何承重内容对照一手来源核实，并在可用时用 /cross 交叉验证有争议或高风险的事实（外部 API、schema、安全声明）。技能所依赖的已核实事实放入 skills/<name>/references/ 作为清理过的受跟踪文件——绝不要在技能中引用 .local/ 路径。
-
评估优先。按 docs/evals.md 创建 skills/<name>/evals/evals.json：≥8 个 should_trigger（变化正式程度、拼写错误、简洁度），≥8 个 should_not_trigger（共享关键词的近似项），3–5 个质量用例，带有平实语言描述的 expected_behavior 断言。如果写不出这些，说明范围不清晰——回到第 1 步。
-
起草 SKILL.md。Frontmatter：name 与文件夹名一致；description 单行、第三人称，[what] + [use when …] + [not for …]，150–400 字符，触发关键词放在前约 120 字符内。正文按 docs/skill-authoring.md 的结构：purpose → when/when-not → 编号工作流 → 输出规范 → 注意事项 → 指针。少于 500 行；确定性步骤作为 scripts/（失败时非零退出）；长材料作为 references/ 并带目录。
-
校验。make check 必须以 0 退出。写入时 hook 已校验该文件；修复它打印的每个错误并分诊每个警告。
-
触发自测。对至少 3 个 should-trigger 和 2 个 should-not-trigger 提示，明确推理：仅凭 description（而非正文）是否会把该提示路由到这里，相对于目录中所有其他技能？修复 description，而不是评估。建议用户对风险最高的用例运行 2–3 次全新会话探测。
-
登记。在 README 目录表中添加/更新该技能的行，添加 CHANGELOG.md 条目，并将该技能放入恰好一个 skills.sh.json 分组（使用引人入胜的一句话分组描述——该文件是仓库的 skills.sh 列表文案）。重新检查兄弟技能的描述是否有新的重叠。不要 commit 或 push——把所有更改留给所有者审查。
输出规范（完成定义）
- skills/<name>/ 包含 SKILL.md + evals/evals.json（按需包含 scripts/references）
- make check → 0 错误；README 目录 + CHANGELOG 已更新
- 3 行摘要：用途、触发短语示例、已知限制
注意事项
- description 保持在一个物理行上——多行值在某些运行时加载失败，且 validator 会阻止它们；绝不要绕过 validator。
- 不要把失败的评估提示逐字粘贴到 description 中（过拟合）；改为泛化缺失的动词/名词。
- 过度触发的修复 = 从实际假阳性重叠中添加有针对性的“Not for …”名词短语；不要删除正向触发。
- 模型升级会改变路由——在摘要中注明，下一次模型发布后应重新运行评估。