用途
add-skill 用于在本仓库（paldom/github-skills）中，以评估优先（eval-first）的方式编写或改进一个生产质量的 Agent Skill，产出位置为 skills/<name>/。它面向的是「一次只做一个技能」的作者场景，要求技能必须修复某个具体观察到的失败，而非泛泛地复述模型已经做得好的内容。
每次开始前应阅读 docs/skill-authoring.md 与 docs/evals.md，它们是该工作流执行的规则手册。若以 /add-skill <args> 形式调用，则将 $ARGUMENTS 视为第一步中要界定范围的技能名称或想法。
何时不使用
- 创建新的 skills 仓库：这发生在本仓库之上的工作区中。
- 基础设施工作（hooks、CI、校验器、文档）：属于普通编辑，按 PR 级别审查。
- 只是复述模型已擅长内容的「技能」：不要构建；技能必须修复某个具体观察到的失败。
主要能力与工作流
-
界定范围（Scope）。用一句话说明该技能做什么以及它修复的具体失败。如果这句话需要用到「和」，就拆成多个技能并逐个完成。检查 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 单行、第三人称、[做什么] + [何时使用 …] + [不适用于 …]，150–400 字符，触发关键词放在前约 120 字符内。正文按 docs/skill-authoring.md 的结构：用途 → 何时/何时不适用 → 编号工作流 → 输出规范 → 注意事项 → 指引。正文少于 500 行；确定性步骤写成 scripts/（失败时以非零码退出）；长材料写成带目录的 references/。
-
校验（Validate）。make check 必须以 0 退出。写入时钩子已经校验过文件；修复它打印的每个错误，逐一分类处理每个警告。
-
触发自测（Trigger self-test）。对至少 3 条 should-trigger 与 2 条 should-not-trigger 提示，显式推理：仅凭 description（而非正文），在目录中所有其他技能的对照下，这条提示是否会被路由到这里？修 description，而不是修 evals。建议用户对风险最高的用例跑 2–3 次全新会话探测。
-
登记（Register）。在 README 目录表中新增/更新该技能行，添加 CHANGELOG.md 条目，并把该技能放入且仅放入一个 skills.sh.json 分组（分组描述要用一句有吸引力的句子——该文件即仓库的 skills.sh 列表文案）。重新检查同级技能的 description 是否出现新的重叠。不要 commit 或 push——把所有改动留给所有者审查。
输出规范（Definition of Done）
- skills/<name>/ 含 SKILL.md + evals/evals.json（按需附 scripts/、references/）
- make check → 0 错误；README 目录 + CHANGELOG 已更新
- 一份 3 行摘要：用途、触发短语示例、已知限制
注意事项
- description 必须保持在一个物理行上——多行值在某些运行时中加载失败，且校验器会拦截；绝不绕过校验器。
- 不要把失败的 eval 提示逐字粘贴进 description（过拟合）；应泛化缺失的动词/名词。
- 过度触发的修复方式 = 针对实际的误报重叠，添加明确的「Not for …」名词短语；不要删除正向触发词。
- 模型升级会改变路由——在摘要中注明，下一次模型发布后应重新运行 evals。