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

agent-skills 的 CLAUDE.md 深度解析让 AI 代理自举式开发 Skill 仓库的治理蓝图【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skillsCLAUDE.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. Dont copy it into another project or a global agent configuration; the reusable assets are the skills inskills/.这条作用域声明是理解整个仓库治理逻辑的关键agent-skills 这个仓库是生产 Skill 的工厂而CLAUDE.md是工厂内部工人的作业手册不是出厂产品。真正可被复用到其他项目的是skills/目录下的技能本身而非这份配置文档。仓库根目录的姊妹文件 AGENTS.md 承担着面向 Claude Code、Cursor、Copilot、Antigravity 等更多代理工具的同类职责并在 CONTRIBUTING.md 的 Repo-scoped files 一节中被明确归为一类写 setup 文档时不应指导用户把这两个文件拷贝进自己的项目或全局代理配置。从源码结构看这个仓库的资产分三层CLAUDE.md的每条规则都指向其中一层Skillsskills/name/SKILL.md——带步骤和退出标准的工作流怎么做the howPersonasagents/role.md——带视角和输出格式的专家角色谁来做the whoSlash commandscommands/、.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-skillsagents/下确实存在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.shreferences/下是 7 份共享检查清单测试、性能、安全、可访问性、可观测性等供多个技能共同引用evals/是技能评估体系cases/存放每个技能的路由/触发用例 JSONfixtures/存放执行型评测所需的真实文件。这份结构的深层意图是目录边界即职责边界。技能只放skills/共享清单只放根级references/评测用例必须与技能同名对应——后文的约定和 CI 校验脚本都建立在这一点上。Skills by Phase技能与开发阶段的映射关系CLAUDE.md将全部技能按软件工程生命周期分成六个阶段这既是一张技能目录也是代理意图 → 技能路由的依据阶段技能Defineinterview-me、idea-refine、spec-driven-developmentPlanplanning-and-task-breakdownBuildincremental-implementation、test-driven-development、context-engineering、source-driven-development、doubt-driven-development、frontend-ui-engineering、api-and-interface-designVerifybrowser-testing-with-devtools、debugging-and-error-recoveryReviewcode-review-and-quality、code-simplification、security-and-hardening、performance-optimizationShipgit-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-developmentPLAN → planning-and-task-breakdownBUILD → incremental-implementation test-driven-development以此类推说明这份阶段划分是整个仓库路由体系的事实标准。Conventions技能编写的硬性约定CLAUDE.md的 Conventions 一节是新增/修改技能时的硬约束每个技能位于skills/name/SKILL.mdYAML 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.mdCLAUDE.md有意不重复其内容而只做链接。anatomy 文档补充了几个值得注意的细节name必须全小写、连字符分隔且与目录名一致description最长 1024 字符且不应概述流程步骤——因为 description 会被注入系统提示词如果它包含流程摘要代理可能照着摘要走而不读完整的 SKILL.md六段结构是推荐模式而非刚性模板等价标题如How It Works、Workflow在保持意图一致时是允许的Context 效率要求SKILL.md控制在 500 行以内支撑文件按需加载progressive disclosure脚本优先于内联代码——执行脚本不消耗上下文只有输出消耗而内联代码块每次加载都要付费若技能附带scripts/下的可运行助手脚本需遵循#!/bin/bashshebang、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.mdpre-flight 检查具体是四步Search the catalog——浏览 README 的技能清单和skills/目录确认没有现成技能覆盖该想法Check open PRs——运行gh pr list --state open或浏览 PR 列表查看同主题的提案near-duplicate 技能的聚簇已经存在别再往里加Read the anatomy——确认想法是一个带验证的可执行工作流而不是模糊建议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校验流程Evalsnode scripts/run-evals.js— 对每个技能做触发/路由评测CI 默认运行--behavioral skill触发带打分的深度运行。scripts/run-evals.js 的头部注释揭示了这套 eval 框架的分层设计Tier 2默认、确定性、CI 安全零依赖包含四类检查Trigger evalsevals/cases/skill.json中的每个正触发 prompt 在给所有技能描述打分时必须把该技能排进 top_k默认 3每个负触发 prompt 不允许把它排到第 1Routing collisions任意两个技能描述不得构成近义重复余弦相似度超阈值即报警/报错守住目录不向重叠技能漂移Coverage schema每个用例文件必须映射到真实技能、skill_name匹配、行为评测符合约定的 JSON 形状执行型评测必须有真实 fixtureRank-1 ratchet--min-rank1 pct在路由质量低于已检入的 CI 基线时让构建失败——质量只进不退。Tier 3opt-in、消耗 token、永不进 CInode scripts/run-evals.js --behavioral skill [--dry-run]在一次性工作区里通过无头claude逐条执行行为评测执行型评测会把files[]fixture 实体化并对完整 stream-json 轨迹打分--dry-run只打印计划不执行。这套机制的设计动机值得点明技能本质是注入代理的指令而路由质量取决于 description 写得是否精准。Tier 2 用确定性的文本打分把技能目录路由准确性变成了可回归测试的工程指标这正是一个纯 Markdown 项目里少有的、可执行的测试。Pull Requests先查重叠小步提交CLAUDE.md对 PR 的纪律浓缩为两条开 PR 之前先搜索上游仓库的 open PR 和 issue 中触碰相同文件/规则的工作。若有重叠应选择协调在其基础上构建、对齐规则、或等它合并后 rebase而不是开一个冲突 PR偏好小而聚焦的 PR避免对广泛共享文件例如scripts/下的文件做大重构——这类文件更容易与在途工作碰撞。CLAUDE.md还特意说明PR 目标指向上游仓库的默认分支典型 fork 工作流中上游 remote 名为upstream、自己的 fork 名为origin但具体的 remote 名字不重要——这条对贡献者尤其是代理相当实用避免了把 remote 命名当成硬编码假设。BoundariesAlways/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.mdfrontmatter 契约、推荐章节流、支撑文件阈值、脚本约定、命名规范结构校验实现scripts/validate-skills.js scripts/lib/skill-lint.jsCI 校验入口与规则库路由/触发评测scripts/run-evals.js evals/README.md两档评测框架与用例目录跨工具集成docs/ 下的各 setup 指南Cursor、Antigravity、Gemini CLI、OpenCode、Copilot 等接入方式这种薄入口 深链接的组织方式本身就是仓库内容治理原则的示范入口文件只保留路由信息和不可妥协的边界细节收敛到单一事实来源从而避免多处复述带来的漂移。小结CLAUDE.md的价值不在于它讲了多深的技术而在于它示范了如何为在仓库内工作的 AI 代理编写治理文档明确作用域仅本仓库、禁止外抄、用目录结构划定职责边界、把编写约定写成可被 CI 校验的规则、用 eval 框架把技能路由质量变成可回归的指标、用 Always/Never 清单给行为划出不可逾越的边界并始终用链接而非复述指向各事实来源。对任何希望让 AI 代理参与维护的开源仓库来说这份 60 行出头的文件就是一个可以直接对照的蓝本。【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考