agent-skills 贡献指南：编写新 Skill、质量基线、Eval 契约与本地验证回路

本文基于 agent-skills 仓库的 CONTRIBUTING.md 编写，系统讲解向该仓库贡献工程 Skill 的完整规则：新技能提案前的五项去重预检、SKILL.md 的 frontmatter 契约与必备目录结构、eval 用例的最小数量要求、被拒变更台账（rejection ledger）的维护约定，以及 session-start 钩子回归测试的本地复现方法。读完后你可以独立发起一个能通过 CI 审查的 skill 贡献 PR，并理解每个检查项背后由哪条验证脚本执行。

一、CONTRIBUTING.md 的定位：规则簿，而非导览图

仓库把贡献者文档明确拆成两层，这是理解整个贡献流程的前提：

• CONTRIBUTING.md 是权威规则簿（authoritative rulebook），所有贡献必须满足的硬性要求都写在这里；
• docs/developer-onboarding.md 是导览图（map），告诉你何时去读哪份文档，以及仓库各部分如何组合。

onboarding 文档把仓库归纳为五个可组合层，贡献时最容易犯的错（把参考材料塞进 skill、让 persona 路由到 persona、跨 skill 复制内容）都源于混淆了这些层的职责：

层	位置	职责	一句话概括
Skills	skills/<name>/SKILL.md	带验证关卡的逐步工作流	How
Personas	agents/<role>.md	有视角和输出格式的角色	Who
Commands	.claude/commands/、.gemini/commands/、commands/	用户入口，编排层	When
References	references/*.md	skill 按需拉取的检查清单	What to check
Evals	evals/cases/<name>.json	证明 skill 能正确触发并改变行为	Does it work

其中命令目录存在 Claude Code、Gemini CLI、Antigravity 三份平行副本，改一处 CI 会检查三处 parity（见 scripts/validate-commands.js）。

二、提出新 Skill 之前的五项预检

agent-skills 的技能目录已覆盖大部分开发生命周期（24 个生命周期技能 + 1 个元技能），很多提案会与既有技能或开放 PR 重叠。CONTRIBUTING.md 要求你在开 PR 之前完成五项检查，避免 reviewer 花时间去重：

1. 搜索技能目录。 浏览 README.md 中的技能清单，并快速扫一遍 skills/ 目录，确认没有现有技能部分或完全覆盖你的想法。
2. 检查开放 PR。 运行 gh pr list --state open（或浏览 PR 页面）查找同主题提案。仓库中已存在近似重复技能的簇，不要再往簇里加。
3. 检查被拒提案台账。 在 evals/skill-impact.md 的 skill-change rejection ledger 中搜索与你的想法重叠的早期提案，并复查其 eval 证据再决定是否重复同样的工作。该台账是 append-only 的，每行记录五个字段：日期、受影响技能、尝试的变更、rank-1 得分（before → after）、被拒 PR 链接与结果（见 evals/skill-impact.md）。
4. 阅读技能解剖规范。 确认你的想法符合 docs/skill-anatomy.md 的格式：是一个带验证的可执行工作流，而不是模糊建议。
5. 在 PR 描述中论证缺口。 明确说明为什么现有技能、开放 PR 或被拒提案都没有覆盖它。如果存在重叠，优先提议扩展现有技能，而不是新开目录。

一条贯穿性原则：如果你的想法是对现有技能的精化（refinement），优先做一处聚焦的编辑，而不是新建一个目录。

三、创建技能：目录、SKILL.md 与 frontmatter 契约

新技能的最小落地步骤是：

1. 在 skills/ 下创建一个 kebab-case 命名的目录；
2. 按 docs/skill-anatomy.md 的格式编写 SKILL.md；
3. 在 SKILL.md 中加入带 name 和 description 字段的 YAML frontmatter；
4. 确保 description 以技能做什么开头（第三人称），随后包含一个或多个 Use when 触发条件。

frontmatter 的精确写法在 docs/skill-anatomy.md 中有规范：

---
name: skill-name-with-hyphens
description: Guides agents through [task/workflow]. Use when [specific trigger conditions].
---

规则与边界条件：

• name 必须小写、连字符分隔，且与目录名一致；
• description 必须先写技能做什么（第三人称），再写清晰的 Use when 触发条件，即同时包含 what 和 when；
• description 有 1024 字符上限；
• 不要在 description 里概括工作流步骤。从源码结构看，description 会被注入 agent 的系统提示，用于技能发现；如果它包含流程摘要，agent 可能照着摘要执行而不再读完整的 SKILL.md——这是 docs/skill-anatomy.md 明确指出的陷阱。

一个真实的对照样例是元技能 skills/using-agent-skills/SKILL.md 的 frontmatter：description 先声明"Discovers and invokes agent skills"（做什么），再写"Use when starting a session or when you need to discover which skill applies"（何时用），完全符合上述契约。

四、技能质量基线：Specific、Verifiable、Battle-tested、Minimal

CONTRIBUTING.md 给每个新技能定了四条质量基线，README.md 的 Contributing 章节引用了同一标准。结合 docs/skill-anatomy.md 的写作原则，每一条可以落到可检查的写作要求上：

• Specific（具体）——可执行的步骤，而不是模糊建议。anatomy 文档给出了正误对照：好的写法是 "Run npm test and verify all tests pass"，坏的写法是 "Make sure the tests work"。
• Verifiable（可验证）——有清晰的退出标准和证据要求。每个 Verification 复选框都必须能用证据（测试输出、构建结果、截图等）核实。
• Battle-tested（实战检验）——基于真实工程工作流，而不是理论理想。
• Minimal（最小化）——只包含正确引导 agent 所需的内容。anatomy 文档的表述更狠："如果删掉某节后 agent 行为不会改变，就删掉它"（token-conscious 原则），并要求 SKILL.md 控制在 500 行以内，更深的参考材料移入支持文件。

五、必备结构：SKILL.md 之外还有 eval 用例文件

这是贡献新技能时最容易被忽略的部分：每个新技能是一个"集合"，不是一个文件。 CONTRIBUTING.md 规定每个新技能必须包含：

• 技能目录下的 SKILL.md；
• 带有效 name 和 description 的 YAML frontmatter；
• 位于 evals/cases/<skill-name>.json 的 eval 用例文件，最低要求：
  • 至少 3 个正触发（positive triggers）；
  • 至少 2 个负触发（negative triggers，尽可能带 owner 字段）；
  • 1 个行为 eval（behavioral eval）。

这些要求由 CI 强制执行。缺少的用例文件、数量不足、未知 kind、无效 fixture 路径、缺失必需 fixture，都是 CI 错误（见 evals/README.md 的 "Adding a skill" 一节）。

5.1 eval 用例文件的真实结构

以 evals/cases/using-agent-skills.json 为例，trigger 部分同时声明正负触发：

{
  "skill_name": "using-agent-skills",
  "trigger": {
    "positive": [
      { "prompt": "Which skill should I use for this task?", "top_k": 3 }
    ],
    "negative": [
      { "prompt": "Debug the null pointer crash in checkout",
        "owner": "debugging-and-error-recovery" }
    ]
  },
  "evals": [
    {
      "id": 1,
      "prompt": "A user asks: 'the login page is broken after yesterday's deploy'. Decide which skill applies and why.",
      "expected_output": "Correct routing through the decision tree with the chosen skill and rationale",
      "files": ["using-agent-skills"],
      "expectations": [
        "The chosen skill matches the decision tree in the meta-skill"
      ]
    }
  ]
}

写触发提示词有明确纪律（evals/README.md）：用用户真实的口吻转述，不要照抄 description——把 description 抄进 prompt 是在"刷 eval"，得不到任何真实信号。如果真实的用户说法无法让技能排进 top-k，那说明 description 缺词汇，这是真发现，应修 description 而不是 eval。负触发上的 owner 字段会把"不能排第一"升级为成对路由测试：runner 会断言 owner 技能压过当前技能，避免提示词不匹配任何技能时测试空转通过。

5.2 行为 eval 的两种 kind

• execution（默认）：每次 eval 在一个一次性 git 仓库中运行，files[] 指向的真实项目输入会从 evals/fixtures/ 物化并提交为基线，评分器审阅完整的执行轨迹（含工具调用）。execution eval 必须被 evals/fixtures/ 下的真实文件支撑——这就是 CONTRIBUTING.md 要求 "execution evals must be backed by real files" 的原因。
• dialogue：仅当技能的交付物就是对话本身时使用（对话型技能无需 fixture，评分器审阅对话轮次本身）。CONTRIBUTING.md 特别强调这是一项需 reviewer 把关的豁免，不是 execution 技能的逃生通道。

5.3 SKILL.md 的推荐章节骨架

frontmatter 是强制项，章节骨架是推荐模式。标准解剖为：

• Overview —— 这个技能做什么、为什么重要；
• When to Use —— 触发条件（含正触发与"何时不该用"的排除项）；
• Process —— 逐步工作流，带编号步骤、代码示例，有决策点时用 ASCII 流程图；
• Common Rationalizations —— agent 用来跳步的借口与逐条反驳（该仓库最标志性的设计，例如 "I'll add tests later" 及其事实性反驳）;
• Red Flags —— 技能被误用时的可观察信号；
• Verification —— 退出标准清单，每项都可由证据核实。

CONTRIBUTING.md 明确：章节名可以是等价的，如 How It Works、Workflow、Core Process，只要保留同样的意图并让技能易读即可——规范约束的是功能，不是字面标题。

六、反模式清单：What Not to Do

CONTRIBUTING.md 列出了五条明确的"不要做"，每一条在 docs/skill-anatomy.md 中都能找到对应的规范依据：

不要做	依据与边界
不要在技能之间复制内容，改为互相引用	anatomy 的 Cross-Skill References 一节：按名字引用，如 "Follow the test-driven-development skill for writing tests."
不要添加模糊建议型技能，只给可执行流程	质量基线 Specific 项
除非内容超过 100 行，不要创建支持文件	anatomy 的 Supporting Files 规则：参考材料超过 100 行才拆文件；50 行以内的模式和原则应保持内联
不要为了对齐别的技能而创建空 scripts/ 目录	只有技能确实包含可运行 helper 时才加 scripts/；空目录只是噪音
不要把参考材料放进技能目录，改用 references/	跨技能共享的清单统一放在仓库根 references/（如 references/security-checklist.md），保持单一事实源

补充两条上下文工程约束（anatomy 的 Context Efficiency 一节）：技能按需加载，启动时只有名字和 description 在上下文里，完整 SKILL.md 在 agent 判定相关后才加载，因此要优先"脚本优于内联代码"（执行脚本只消耗其输出的 token）、文件引用保持一层深度（直接从 SKILL.md 链到支持文件，不经过中间文档）。若技能带 scripts/，脚本需遵循 #!/bin/bash、set -e、状态信息写 stderr、机器可读输出（JSON）写 stdout、临时文件用 cleanup trap 的约定。

七、修改现有技能与被拒变更台账

修改现有技能前，同样先查 evals/skill-impact.md，看是否有人对同一技能提过被拒的变更，并复查其 eval 证据。修改时的三条要求：

• 变更保持聚焦和最小化；
• 保留原有结构与语气；
• 编辑后验证 YAML frontmatter 仍然有效。

台账维护有一条容易做错的流程细节：如果某个技能或 description 变更被基于 eval 结果拒绝，需要往台账追加一行——包含日期、受影响技能、简洁的变更描述、before-to-after rank-1 得分、被拒 PR 链接与结果。并且这条台账更新要单独在默认分支上落地，不能只留在被拒的提案分支上：提案分支关闭或 force-push 时，记录会随之丢失。这是 CONTRIBUTING.md 中少见的"流程性"要求，目的是让后续贡献者能查到"这条路为什么不通"。

八、仓库作用域文件与语言策略

8.1 AGENTS.md 与 CLAUDE.md 不可外带

仓库根目录的 AGENTS.md 和 CLAUDE.md 配置的是在本仓库内工作的 agent（例如 AGENTS.md 开篇即声明其 scope 仅限本仓库，不可复制到其他项目或全局 agent 配置）。写设置指南或文档时，CONTRIBUTING.md 明确要求：不要指示用户把这两个文件拷进他们自己的项目。可复用的资产是 skills/ 里的技能，不是这两个文件。

8.2 不接受翻译

文档（README、docs/）和技能的翻译不被接受。理由：技能与文档持续演进，翻译副本会漂移失步，而长期维护只能依赖 agent 翻译加社区纠错，维护成本高、价值有限。所有技能、文档与贡献一律保持英文。

九、Hook 回归测试：session-start 注入链路

9.1 钩子做什么

session-start 钩子 hooks/session-start.sh 负责把 using-agent-skills 元技能注入每一个新的 Claude Code 会话。从源码看（hooks/session-start.sh）：

• 所有输出路径都必须发出标准 SessionStart 信封 {"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "..."}}——验证 hook 输出的宿主（Codex CLI、Claude Code）会拒绝其他形状；
• 若 command -v jq 失败（PATH 上找不到 jq），钩子优雅降级，发出一条带 jq is required 指引信息的 payload（建议 brew install jq 或 apt-get install jq）；
• 否则用 jq -cn 把元技能全文读入 additionalContext，构建转义安全的 JSON（路径解析为仓库根下的 skills/using-agent-skills/SKILL.md）。

9.2 什么时候必须跑测试

任何 PR 只要触碰以下两个文件之一，就必须先跑回归测试 hooks/session-start-test.sh：

• hooks/session-start.sh
• skills/using-agent-skills/SKILL.md（钩子嵌入的元技能内容）

bash hooks/session-start-test.sh

预期输出：session-start JSON payload OK（见 hooks/session-start-test.sh）。任何断言失败脚本都会以非零码退出。测试脚本自身用 set -euo pipefail、mktemp + trap 清理临时文件，先探测本机是否有 jq，再调用钩子、解析其 JSON 输出，按分支断言（有 jq 时断言注入的元技能内容；无 jq 时断言 fallback 指引文案）。

9.3 本地复现 no-jq 回退分支

钩子在 PATH 上没有 jq 时降级为 INFO 优先级的 payload。要本地走这条分支，把 jq 所在目录从 PATH 中剔除后再跑测试：

JQ_DIR=$(dirname "$(command -v jq)")
PATH=$(echo "$PATH" | tr ':' '\n' | grep -v "^${JQ_DIR}$" | tr '\n' ':' | sed 's/:$//') \
  bash hooks/session-start-test.sh

CONTRIBUTING.md 对这个技巧给出了明确的适用前提与局限：

• 它要求 jq 独占一个目录（如 Homebrew 的 /opt/homebrew/bin 或手动安装的 /usr/local/bin），剔除该目录不会影响 mktemp 等测试依赖的其他工具；
• 如果你的 jq 与测试依赖的其他工具共享系统 bin（例如 /usr/bin 里同时有 mktemp），这种剔除法会误伤。更简单的替代方案是通过另一个包管理器单独安装 jq，使其拥有独立的 bin 目录，然后重跑。

原理：剔除后钩子内的 command -v jq 检查失败，INFO 优先级回退分支执行，测试随即断言 jq is required 指引文案而非正常 payload。

十、报告问题与许可证

发现以下情况应开 issue：

• 某个技能给出了错误或缺过时的指引；
• 常见工程工作流缺少覆盖；
• 技能之间存在不一致。

如果技能的指引在你的项目里实际失效（例如它假设 npm test，而你的仓库是 Maven 或 Gradle），使用仓库提供的 Skill gap 表单（issue template）。该表单收集四样东西：受影响技能、相关摘录、你的项目上下文、你实际改做了什么——足够维护者分诊，无需自由发挥的长文。

最后，CONTRIBUTING.md 的 License 一节声明：通过贡献，你同意你的贡献以 MIT 许可证 授权（与 LICENSE 一致）。

十一、提交 PR 前的本地验证回路

CONTRIBUTING.md 的每条要求最终都落到可本地执行的验证命令上。结合 docs/developer-onboarding.md 的验证回路与 evals/README.md 的三层 eval 体系，PR 前应跑通与变更相关的子集：

# Tier 1（结构性）：frontmatter、命名、必备章节
node scripts/validate-skills.js

# 三个命令目录的 parity 与描述同步（触碰任何命令目录时必跑）
node scripts/validate-commands.js

# Tier 2（触发与路由）：正提示排进 top-k、负提示不冲突
node scripts/run-evals.js

# Tier 3（行为级，按需，消耗 token；--dry-run 只打印计划）
node scripts/run-evals.js --behavioral <skill-name> --dry-run

# 触碰 hooks/session-start.sh 或 using-agent-skills 时必跑
bash hooks/session-start-test.sh

几条值得注意的执行细节：

• Tier 1 的实现是 scripts/validate-skills.js：它遍历 skills/ 下每个目录，对每个技能调用 scripts/lib/skill-lint.js 中的 lint 规则（规则本身与 CLI 解耦，可单元测试），有错误时以退出码 1 结束（见 scripts/validate-skills.js）。
• Tier 2 的判定阈值：CI 以 --min-rank1 80 执行，在仓库检入的 86% rank-1 基线之下留有缓冲，避免无关的 description 编辑立刻把 CI 打红；地板只可上调不可下调。描述碰撞检查在成对相似度 ≥75% 时报错、≥50% 时告警。Tier 2 是对路由的词汇级近似（对 description 做词干化 TF-IDF），因此 Tier 2 变红通常意味着"修你的 description"，而不是修 eval。
• 本地环境要求（docs/developer-onboarding.md）：Node 20+（CI 所用版本）、bash（推荐装 jq）用于钩子测试、gh CLI 用于查重复 PR、仅当本地跑 Tier 3 行为 eval 时才需要 Claude Code。仓库无构建步骤、无 package.json，验证器都是纯 Node 脚本。

对应 onboarding 文档的 pre-PR checklist，可浓缩为六条自查：

• [ ] Tier 1 绿：node scripts/validate-skills.js
• [ ] Tier 2 绿：node scripts/run-evals.js
• [ ] 若触碰命令目录：命令 parity 绿
• [ ] 若触碰 hooks/ 或 using-agent-skills：钩子测试绿
• [ ] 新技能：eval 用例文件存在且满足最小触发/行为数量
• [ ] 新技能：PR 描述中论证了缺口，且已查过目录与开放 PR；无跨技能内容复制

一个通过 Tier 1 + Tier 2 + 命令 parity 的绿色 PR 才具备被审查的条件；不绿的 PR 会在内容被阅读之前就先因机械问题被打回。

小结

向 agent-skills 贡献的核心链路可以概括为：先查台账去重（目录 → 开放 PR → 被拒台账）→ 按 frontmatter 契约与标准解剖写 SKILL.md → 同步交付 eval 用例（3 正 + 2 负 + 1 行为）→ 触碰钩子或元技能就跑回归测试 → 提交前跑完整验证回路。这份规则簿的深层逻辑与仓库自身的产品主张一致——技能要求 agent 的每一步都可验证，那么对贡献者，规则本身也是可验证的：每一条要求背后都有一条脚本或测试在执行。