agent-skills 的 CLAUDE.md 深度解析：让 AI 代理"自举式"开发 Skill 仓库的治理蓝图

CLAUDE.md 是 agent-skills 仓库为"在仓库内部工作的 AI 编码代理"准备的专属配置入口：它定义了项目结构、技能（Skill）的编写规范、验证与评估命令、PR 纪律和不可逾越的边界，是代理在本仓库贡献内容时的第一份"岗位说明书"。读完本文，你将理解这份文件为什么被刻意限制在仓库作用域内、它与 AGENTS.md/CONTRIBUTING.md/docs/skill-anatomy.md 如何分工协作，以及如何沿着它给出的约定、校验脚本和 eval 框架，完整地走通一次"新增/修改技能"的实操路径。

定位：这是"仓库作用域"文件，不是可复制的通用模板

CLAUDE.md 开头就给出了一条醒目提示：

Scope: This file configures agents working on the [addyosmani/agent-skills] repository itself, not other projects. Don't copy it into another project or a global agent configuration; the reusable assets are the skills in skills/.

这条作用域声明是理解整个仓库治理逻辑的关键：agent-skills 这个仓库是"生产 Skill 的工厂"，而 CLAUDE.md 是工厂内部工人的作业手册，不是出厂产品。真正可被复用到其他项目的是 skills/ 目录下的技能本身，而非这份配置文档。仓库根目录的姊妹文件 AGENTS.md 承担着面向 Claude Code、Cursor、Copilot、Antigravity 等更多代理工具的同类职责，并在 CONTRIBUTING.md 的 "Repo-scoped files" 一节中被明确归为一类：写 setup 文档时，不应指导用户把这两个文件拷贝进自己的项目或全局代理配置。

从源码结构看，这个仓库的资产分三层，CLAUDE.md 的每条规则都指向其中一层：

• Skills（skills/<name>/SKILL.md）——带步骤和退出标准的工作流，"怎么做（the how）"；
• Personas（agents/<role>.md）——带视角和输出格式的专家角色，"谁来做（the who）"；
• Slash commands（commands/、.claude/commands/ 等）——用户可见的入口，"何时触发（the when）"。

Project Structure：七个目录各管一段生命周期

CLAUDE.md 给出的项目结构表是导航整个仓库的最小地图：

skills/       → Core skills (SKILL.md per directory)
agents/       → Reusable agent personas (code-reviewer, test-engineer, security-auditor, web-performance-auditor)
hooks/        → Session lifecycle hooks
.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship; plus /webperf specialist audit)
references/   → Supplementary checklists (testing, performance, security, accessibility, observability)
evals/        → Skill eval cases + framework (see evals/README.md)
docs/         → Setup guides for different tools

对照仓库实际内容可以逐一确认：

• skills/ 下共 24 个技能目录，覆盖 23 个生命周期技能加 1 个元技能 using-agent-skills；
• agents/ 下确实存在 code-reviewer.md、test-engineer.md、security-auditor.md、web-performance-auditor.md 四个专家角色文件；
• hooks/ 存放会话生命周期钩子，例如 session-start.sh 会在每次新的 Claude Code 会话中注入 using-agent-skills 元技能，并有配套的回归测试 session-start-test.sh；
• references/ 下是 7 份共享检查清单（测试、性能、安全、可访问性、可观测性等），供多个技能共同引用；
• evals/ 是技能评估体系，cases/ 存放每个技能的路由/触发用例 JSON，fixtures/ 存放执行型评测所需的真实文件。

这份结构的深层意图是：目录边界即职责边界。技能只放 skills/，共享清单只放根级 references/，评测用例必须与技能同名对应——后文的约定和 CI 校验脚本都建立在这一点上。

Skills by Phase：技能与开发阶段的映射关系

CLAUDE.md 将全部技能按软件工程生命周期分成六个阶段，这既是一张技能目录，也是代理"意图 → 技能"路由的依据：

阶段	技能
Define	interview-me、idea-refine、spec-driven-development
Plan	planning-and-task-breakdown
Build	incremental-implementation、test-driven-development、context-engineering、source-driven-development、doubt-driven-development、frontend-ui-engineering、api-and-interface-design
Verify	browser-testing-with-devtools、debugging-and-error-recovery
Review	code-review-and-quality、code-simplification、security-and-hardening、performance-optimization
Ship	git-workflow-and-versioning、ci-cd-and-automation、deprecation-and-migration、documentation-and-adrs、observability-and-instrumentation、shipping-and-launch

这套阶段划分与仓库元技能 using-agent-skills/SKILL.md 中的技能发现决策树完全一致：任务到达时先判断所处阶段，再落到对应技能；例如"正在实现代码？"进入 incremental-implementation，若是 UI 工作则分叉到 frontend-ui-engineering，若担心上下文不足则分叉到 context-engineering。AGENTS.md 中的 "Intent → Skill Mapping" 和 "Lifecycle Mapping" 也是同一映射的另一份表述（DEFINE → spec-driven-development，PLAN → planning-and-task-breakdown，BUILD → incremental-implementation + test-driven-development，以此类推），说明这份阶段划分是整个仓库路由体系的事实标准。

Conventions：技能编写的硬性约定

CLAUDE.md 的 "Conventions" 一节是新增/修改技能时的硬约束：

• 每个技能位于 skills/<name>/SKILL.md；
• YAML frontmatter 必须包含 name 和 description 字段；
• description 以"该技能做什么"（第三人称）开头，随后是触发条件（"Use when..."）；
• 每个技能都应包含 Overview、When to Use、Process、Common Rationalizations、Red Flags、Verification 六段；
• 共享引用放在根级 references/ 目录；正在形成的惯例是：自包含、可分发的技能把自己专属的引用收进 skills/<name>/references/；
• 只有当内容超过 100 行时才创建支撑文件。

这些约定并非纸面条款，而是被 CI 脚本逐条机器校验的。scripts/validate-skills.js 是校验入口，它遍历 skills/ 下每个目录并调用 scripts/lib/skill-lint.js 中的 lintSkill()——注释明确写道"规则本身住在 skill-lint.js（单一事实来源，可导入、可单测），本文件只是薄封装"。其运行逻辑是：skills/ 目录不存在直接报错；对每个技能目录产出 errors/warnings/exempt 三类结果；只要存在 error 就以退出码 1 结束，并打印 FAILED 汇总行。也就是说，frontmatter 缺失、description 不合规这类问题会在 CI 层面被拦截，而不是靠 reviewer 目检。

约定的完整规范落在 docs/skill-anatomy.md，CLAUDE.md 有意不重复其内容而只做链接。anatomy 文档补充了几个值得注意的细节：

• name 必须全小写、连字符分隔，且与目录名一致；description 最长 1024 字符，且不应概述流程步骤——因为 description 会被注入系统提示词，如果它包含流程摘要，代理可能照着摘要走而不读完整的 SKILL.md；
• 六段结构是"推荐模式"而非刚性模板，等价标题（如 How It Works、Workflow）在保持意图一致时是允许的；
• Context 效率要求 SKILL.md 控制在 500 行以内，支撑文件按需加载（progressive disclosure）；脚本优先于内联代码——执行脚本不消耗上下文，只有输出消耗，而内联代码块每次加载都要付费；
• 若技能附带 scripts/ 下的可运行助手脚本，需遵循 #!/bin/bash shebang、set -e 快速失败、状态消息写 stderr、机器可读 JSON 写 stdout、临时文件设 cleanup trap 等约定。

一个符合全部约定的 frontmatter 实例，可参考元技能 skills/using-agent-skills/SKILL.md 的开头：

---
name: using-agent-skills
description: Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.
---

description 先说做什么（Discover and invoke agent skills），再用 "Use when starting a session..." 给出触发条件，正是约定的标准形态。

Contributing：新技能提案的前置检查清单

CLAUDE.md 的 "Contributing" 一节把新技能流程收敛为一句话加三个链接：先跑 CONTRIBUTING.md 中的 pre-flight 检查——搜索现有目录、检查 open PR、确认想法符合 docs/skill-anatomy.md 的格式、论证缺口（justify the gap）；并且优先扩展已有技能，而不是新增近似重复的技能。它特别强调 "CONTRIBUTING.md is the single source of truth for this workflow; do not restate its checklist here or elsewhere, link to it"——这本身就是一条反重复的内容治理原则，与 "Never: Duplicate content between skills" 一脉相承。

展开到 CONTRIBUTING.md，pre-flight 检查具体是四步：

1. Search the catalog——浏览 README 的技能清单和 skills/ 目录，确认没有现成技能覆盖该想法；
2. Check open PRs——运行 gh pr list --state open（或浏览 PR 列表），查看同主题的提案，"near-duplicate 技能的聚簇已经存在，别再往里加"；
3. Read the anatomy——确认想法是一个"带验证的可执行工作流"，而不是模糊建议；
4. Justify the gap——在 PR 描述中明确说明为什么现有技能或 open PR 没覆盖；若重叠，建议改为扩展现有技能。

此外，新技能还需要满足 CONTRIBUTING.md "Structure" 一节的额外结构要求，其中与 CLAUDE.md 形成互补的一点是：每个新技能必须在 evals/cases/<skill-name>.json 提供 eval 用例文件，至少 3 个正触发、2 个负触发（尽量带 owner）、1 个行为评测；执行型评测必须由 evals/fixtures/ 下的真实文件支撑，对话型技能可使用 reviewer 把关的 kind: "dialogue" 评测。CI 会强制这些要求。

Commands：验证与评估两条自动化防线

CLAUDE.md 的 "Commands" 一节列出了本仓库仅有的两类自动化命令：

• npm test — 不适用（这是一个文档项目，没有传统测试套件）；
• Validate：检查所有 SKILL.md 是否具备含 name 和 description 的有效 YAML frontmatter——即上一节所述的 scripts/validate-skills.js 校验流程；
• Evals：node scripts/run-evals.js — 对每个技能做触发/路由评测（CI 默认运行）；--behavioral <skill> 触发带打分的深度运行。

scripts/run-evals.js 的头部注释揭示了这套 eval 框架的分层设计：

• Tier 2（默认、确定性、CI 安全），零依赖，包含四类检查：
  • Trigger evals：evals/cases/<skill>.json 中的每个正触发 prompt 在给所有技能描述打分时，必须把该技能排进 top_k（默认 3）；每个负触发 prompt 不允许把它排到第 1；
  • Routing collisions：任意两个技能描述不得构成近义重复（余弦相似度超阈值即报警/报错），守住目录不向重叠技能漂移；
  • Coverage + schema：每个用例文件必须映射到真实技能、skill_name 匹配、行为评测符合约定的 JSON 形状，执行型评测必须有真实 fixture；
  • Rank-1 ratchet：--min-rank1 <pct> 在路由质量低于已检入的 CI 基线时让构建失败——质量只进不退。
• Tier 3（opt-in、消耗 token、永不进 CI）：node scripts/run-evals.js --behavioral <skill> [--dry-run]，在一次性工作区里通过无头 claude 逐条执行行为评测，执行型评测会把 files[] fixture 实体化并对完整 stream-json 轨迹打分；--dry-run 只打印计划不执行。

这套机制的设计动机值得点明：技能本质是"注入代理的指令"，而路由质量取决于 description 写得是否精准。Tier 2 用确定性的文本打分把"技能目录路由准确性"变成了可回归测试的工程指标，这正是一个纯 Markdown 项目里少有的、可执行的"测试"。

Pull Requests：先查重叠，小步提交

CLAUDE.md 对 PR 的纪律浓缩为两条：

1. 开 PR 之前，先搜索上游仓库的 open PR 和 issue 中触碰相同文件/规则的工作。若有重叠，应选择协调（在其基础上构建、对齐规则、或等它合并后 rebase），而不是开一个冲突 PR；
2. 偏好小而聚焦的 PR，避免对广泛共享文件（例如 scripts/ 下的文件）做大重构——这类文件更容易与在途工作碰撞。

CLAUDE.md 还特意说明：PR 目标指向上游仓库的默认分支；典型 fork 工作流中上游 remote 名为 upstream、自己的 fork 名为 origin，但"具体的 remote 名字不重要"——这条对贡献者（尤其是代理）相当实用，避免了把 remote 命名当成硬编码假设。

Boundaries：Always/Never 清单

CLAUDE.md 的收尾是显式的行为边界：

Always：

• 创建新技能目录前跑 CONTRIBUTING.md 的 pre-flight 检查；
• 新技能遵循 skill-anatomy.md 的格式；
• 开新 PR 前检查上游 open PR 和 issue 是否有重叠。

Never：

• 添加"模糊建议"而非"可执行流程"的技能；
• 在技能之间复制内容——应改为引用其他技能。

这份 Always/Never 清单与前文各节一一呼应：pre-flight 对应 Contributing 一节，anatomy 格式对应 Conventions 一节，重叠检查对应 Pull Requests 一节。可以把它理解为把全文规则压缩成代理可直接执行的决策表——这正是 agent-skills 自己倡导的"process over prose"写作风格在 CLAUDE.md 上的体现。

关联文档：CLAUDE.md 的引用网络

把 CLAUDE.md 放进仓库文档体系里看，它处于"入口层"，通过链接把细节推给各自的事实来源：

关注点	事实来源	说明
新技能完整流程	CONTRIBUTING.md	唯一权威规则书，含 pre-flight、技能质量四标准（Specific/Verifiable/Battle-tested/Minimal）、翻译政策、钩子测试
技能结构规范	docs/skill-anatomy.md	frontmatter 契约、推荐章节流、支撑文件阈值、脚本约定、命名规范
结构校验实现	scripts/validate-skills.js + scripts/lib/skill-lint.js	CI 校验入口与规则库
路由/触发评测	scripts/run-evals.js + evals/README.md	两档评测框架与用例目录
跨工具集成	docs/ 下的各 setup 指南	Cursor、Antigravity、Gemini CLI、OpenCode、Copilot 等接入方式

这种"薄入口 + 深链接"的组织方式本身就是仓库内容治理原则的示范：入口文件只保留路由信息和不可妥协的边界，细节收敛到单一事实来源，从而避免多处复述带来的漂移。

小结

CLAUDE.md 的价值不在于它讲了多深的技术，而在于它示范了如何为"在仓库内工作的 AI 代理"编写治理文档：明确作用域（仅本仓库、禁止外抄）、用目录结构划定职责边界、把编写约定写成可被 CI 校验的规则、用 eval 框架把"技能路由质量"变成可回归的指标、用 Always/Never 清单给行为划出不可逾越的边界，并始终用链接而非复述指向各事实来源。对任何希望让 AI 代理参与维护的开源仓库来说，这份 60 行出头的文件就是一个可以直接对照的蓝本。