用途
add-skill 是一个技能创作工作流工具，用于在本仓库中按照"评测优先"（eval-first）的方式，创作或改进一个生产级 Agent Skill，成果放在 skills/<name>/ 目录下。
它属于规则驱动的工作流：开始前每个会话需先阅读 docs/skill-authoring.md 和 docs/evals.md 一次，这两份文档是本工作流所执行的规则手册。如果以 /add-skill <args> 形式调用，则把 $ARGUMENTS 当作第 1 步要界定的技能名称或想法。
不适用场景
- 创建新的技能仓库：那属于本仓库上层的工作区。
- 基础设施类工作（hooks、CI、validator、docs）：属于普通编辑，按 PR 级别审查。
- 只是重复模型已经做得很好之事的"技能"：不要构建；技能必须修复一个具体被观察到的失败。
工作流
-
界定范围（Scope）：用一句话说明该技能做什么以及它修复的具体失败。如果这句话需要用到"and"，就拆成多个技能，一次做一个。检查 skills/ 与 README 目录是否有重叠——相邻近的描述会互相抢触发；调整范围或规划互不重叠的措辞。
-
收集资料（Gather）：递归阅读 .local/，每个子文件夹与文件都是素材（研究、示例、约束）。然后在其之外做调研：对该主题进行网络搜索以获取当前事实、官方文档和先例；对任何承重的信息用一手来源核实，对存在争议或高风险的事实（外部 API、schema、安全声明）在可用时用 /cross 交叉验证。技能所依赖的、已验证的事实放到 skills/<name>/references/ 下，作为清理过的、受跟踪的文件——绝不要在技能中引用 .local/ 路径。
-
先写评测（Evals first）：按 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 → 编号工作流 → 输出规范 → gotchas → 指针。少于 500 行；确定性步骤写成 scripts/（失败时非零退出）；长材料写成带 TOC 的 references/。
-
校验（Validate）：make check 必须退出码为 0。写时钩子已经校验过该文件；修复它打印的每一个错误并分级处理每一个警告。
-
触发自测（Trigger self-test）：针对至少 3 条 should-trigger 和 2 条 should-not-trigger 提示，明确推理：仅凭 description（而非正文），在目录中所有其他技能的对照下，会把该提示路由到这里吗？修描述，而不是修评测。建议用户对最有风险的用例做 2–3 次全新会话探测。
-
注册（Register）：在 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 行摘要：用途、触发短语示例、已知限制。
注意事项（Gotchas）
- 让 description 保持在一个物理行上——多行值在部分运行时中加载失败，且校验器会阻止它们；绝不要绕过校验器。
- 不要把失败的评测提示逐字粘贴进 description（过拟合）；应泛化缺失的动词/名词。
- 过度触发的修复方式 = 针对实际误报重叠，添加有针对性的 "Not for …" 名词短语；不要删除正向触发词。
- 模型升级会改变路由——在摘要中注明，下一次模型发布后应重新运行评测。