Agent Skills 全解析：为 AI 编码智能体打造的软件工程技能包

2026-09-05 16:07:41作者：戚魁泉Nursing

Agent Skills（agent-skills）是一个面向 AI 编码智能体的生产级工程技能包，它将资深工程师在软件开发生命周期中依赖的工作流、质量门禁与最佳实践封装成一组可被智能体一致执行的 Markdown 技能（Skill）。读完本文，你将掌握该项目的完整安装方式（npx skills 与各工具原生集成）、9 个斜杠命令与 25 个技能的职责划分、SKILL.md 的标准解剖结构与反合理化（anti-rationalization）设计，以及如何在新项目与存量代码库中落地整套技能体系。

一、核心思路：把资深工程师的纪律注入智能体

AI 编码智能体默认走"最短路径"——这往往意味着跳过规格说明、测试、安全评审等让软件可靠的工程实践。Agent Skills 的定位就是给智能体一套结构化的工作流，强制执行与资深工程师同等的工程纪律。每个技能编码的是经过验证的工程判断：何时写规格、测什么、如何评审、何时发布。

整个技能包围绕开发生命周期的六个阶段组织，README 中的总览图清晰呈现了这一主线：

  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
 ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
 │ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │  QA  │ ───▶ │  Go  │
 │Refine│      │  PRD │      │ Impl │      │Debug │      │ Gate │      │ Live │
 └──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘
  /spec          /plan          /build        /test         /review       /ship

这些技能融入了 Google 工程文化的经典概念（源自 Software Engineering at Google 与 Google 工程实践指南）：API 设计中的 Hyrum's Law、测试中的 Beyoncé Rule 与测试金字塔（80/15/5）、代码评审中的变更规模（约 100 行）与评审速度规范、简化中的 Chesterton's Fence、Git 工作流中的主干开发（trunk-based development）、CI/CD 中的 Shift Left 与特性开关，以及把"代码即负债"作为核心心态的弃用与迁移技能。这些不是抽象原则，而是直接嵌入智能体逐步执行的工作流中。

二、安装：一条命令或原生集成

2.1 最快路径：skills CLI（任意智能体）

通过开放的 skills CLI（vercel-labs/skills）可安装到 70+ 智能体（Claude Code、Cursor、Codex、Copilot、Cline 等）：

npx skills add addyosmani/agent-skills            # install all 25 skills
npx skills add addyosmani/agent-skills --list     # browse before installing

也可以只安装单个技能：

npx skills add addyosmani/agent-skills --skill code-review-and-quality   # five-axis review before merge
npx skills add addyosmani/agent-skills --skill interview-me              # requirements interrogation, one question at a time
npx skills add addyosmani/agent-skills --skill test-driven-development   # red-green-refactor, enforced

单技能安装的已知局限：按技能单独 npx 安装只会复制 skills/<name>/ 目录，不会带上仓库根目录的 references/ 共享清单。技能本身仍可工作，但指向共享清单的路径会失效。建议整仓集成、clone 仓库，或把所需清单复制到已安装技能的 references/ 目录内。这一可移植性缺口已被跟踪（issue #361）。

2.2 各工具原生集成

Claude Code（官方推荐）

Marketplace 方式安装：

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

若遇到 SSH 报错：marketplace 通过 SSH 克隆仓库，若未配置 SSH key，可以改用 HTTPS 完整 URL 强制走 HTTPS 克隆；若 /plugin install 仍报 git@github.com: Permission denied (publickey)，推荐的规避方案是配置 Git 一次性重写 SSH URL：

git config --global url."https://github.com/".insteadOf git@github.com:

本地/开发模式：

git clone https://gitcode.com/GitHub_Trending/agentskill/agent-skills.git
claude --plugin-dir /path/to/agent-skills

Cursor：将工作流技能放在 .cursor/skills/ 下（从 agent-skills/skills/ 同步），短策略放在 .cursor/rules/*.mdc —— 不要把完整技能粘贴进 rules。详见 docs/cursor-setup.md。

Antigravity CLI：作为原生插件安装技能与子智能体。注意在受影响的 Antigravity CLI 版本中，遗留命令 TOML 会报告"已转换"但其包装命令不可发现，需要直接调用底层的命名空间技能。详见 docs/antigravity-setup.md。

agy plugin install https://github.com/addyosmani/agent-skills.git
# 或本地克隆后：
agy plugin install ./agent-skills

Gemini CLI：安装为原生技能以支持自动发现，或写入 GEMINI.md 作为持久上下文。详见 docs/gemini-cli-setup.md。

gemini skills install https://github.com/addyosmani/agent-skills.git --path skills
# 或本地克隆：
gemini skills install ./agent-skills/skills/

Windsurf：将技能内容加入 Windsurf rules 配置，详见 docs/windsurf-setup.md。

OpenCode：将技能复制到 .opencode/skills/（或 ~/.config/opencode/skills/），添加项目级 AGENTS.md，并使用内置 skill 工具做智能体驱动执行；可选的斜杠命令放在 .opencode/commands/。详见 docs/opencode-setup.md。

GitHub Copilot：把 agents/ 下的角色定义作为 Copilot 人格，技能内容放入 .github/copilot-instructions.md。详见 docs/copilot-setup.md。

Kiro IDE & CLI：技能存放在 .kiro/skills/，支持项目级或全局级，Kiro 同时支持 Agents.md。

Codex（Codex CLI v0.122+）：安装为原生 Codex 插件。第一条命令注册 marketplace，第二条安装插件：

codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills

Codex 通过 .codex-plugin/plugin.json 直接读取根 skills/ 目录。安装后在聊天中使用 @ 调用技能（如 @spec-driven-development）。详见 docs/codex-setup.md。

Command Code：使用内置 cmd skills 命令原生安装，它会克隆仓库、发现每个 SKILL.md 并安装到 .commandcode/skills/：

cmd skills add addyosmani/agent-skills            # pick skills to install (project)
cmd skills add addyosmani/agent-skills --global   # install for all projects (~/.commandcode/skills/)
cmd skills add addyosmani/agent-skills -s spec-driven-development  # install a specific skill

安装后的技能会出现在 TUI 斜杠菜单中，如 /spec-driven-development。详见 docs/commandcode-setup.md。

其他智能体：技能就是纯 Markdown——任何接受系统提示词或指令文件的智能体都能使用。通用做法（clone 仓库 → 选择技能 → 载入智能体）见 docs/getting-started.md。

三、斜杠命令：生命周期入口

命令是入口点，共 9 个斜杠命令映射到开发生命周期，每个命令自动激活对应技能：

你在做什么	命令	关键原则
定义要构建什么	`/spec`	规格先于代码
规划如何构建	`/plan`	小而原子的任务
增量构建	`/build`	一次一片（vertical slice）
证明它可用	`/test`	测试即证据
设定质量标准	`/constraints`	一次决定，处处执行
合并前评审	`/review`	改善代码健康度
审计 Web 性能	`/webperf`	先度量再优化
简化代码	`/code-simplify`	清晰优于聪明
上线发布	`/ship`	更快即更安全

命令本体是仓库 commands/ 目录下的 TOML 文件（如 commands/build.toml、commands/spec.toml、commands/ship.toml），每个文件由 description 与 prompt 两部分组成，prompt 指示智能体调用相应技能并按固定流程执行。例如 commands/spec.toml 要求先就目标用户、核心功能与验收标准、技术栈约束、边界（always do / ask first / never do）提问，再产出覆盖六大核心区域（目标、命令、项目结构、代码风格、测试策略、边界）的结构化规格，并保存为项目根目录的 SPEC.md。

/build auto：一次审批，自主执行整个计划。 该模式在规格存在时把规划 + 构建合并为一次运行——移除的是任务之间的人工步进，而不是验证：每个任务仍然测试驱动、独立提交，遇到失败或高风险步骤会暂停。从 commands/build.toml 可以看到其严谨的执行协议：

默认模式只实现下一个待办任务（RED → GREEN → 回归 → 构建 → 提交 → 标记完成）；
自主模式要求 SPEC.md 存在于已知路径（SPEC.md、docs/SPEC.md 或 spec/ 下），README 或任意文档不算数；
要求干净基线（git status --porcelain），避免自主提交吸收无关本地改动；
设置唯一人工检查点：完整呈现计划并等待明确肯定（"approve"/"go"/"yes"），含糊回应（"looks reasonable"）视为未批准；
按依赖顺序执行全部任务，每个任务只 stage 该任务触碰的文件，绝不盲目 git add -A，每个任务一次提交，使任意点都是干净的回滚点；
测试无法通过、规格含糊、或任务高风险/不可逆（auth 变更、破坏性数据迁移、支付、删除、部署、涉及密钥、无法 git revert）时停下询问，而非硬推。

技能还会基于你正在做的事自动激活——设计 API 触发 api-and-interface-design，构建 UI 触发 frontend-ui-engineering，依此类推。

四、技能目录：24 个生命周期技能 + 1 个元技能

技能包共 25 个技能——24 个生命周期技能加上 using-agent-skills 元技能。每个技能都是包含步骤、验证门禁与反合理化表格的结构化工作流，也可以被直接引用。

Meta —— 发现哪个技能适用

技能	作用	适用时机
using-agent-skills	把 incoming 工作映射到正确的技能工作流，并定义共享操作规则	会话开始或判断该用哪个技能时

Define —— 明确要构建什么

技能	作用	适用时机
interview-me	一次一问的访谈，提取用户真正想要的（而非自认为该想要的），直到约 95% 置信度	需求含糊，或用户唤起 "interview me" / "grill me"
idea-refine	结构化发散/收敛思考，把模糊想法变成具体提案	有粗略概念需要探索时
spec-driven-development	写 PRD：目标、命令、结构、代码风格、测试、边界——先于任何代码	新项目、新功能或重大变更
constraint-driven-development	访谈得出带合理默认阈值的质量标准，写 CONSTRAINTS.md，按成本放置每项检查，并捕捉智能体为求绿而静默检查、跳测的行为	没有成文标准，或智能体产出超过阅读能力

Plan —— 拆解

技能	作用	适用时机
planning-and-task-breakdown	把规格拆成小的、可验证的任务，含验收标准与依赖排序	有规格、需要可实施单元时

Build —— 写代码

技能	作用	适用时机
incremental-implementation	薄垂直切片：实现、测试、验证、提交；特性开关、安全默认、可回滚	任何触碰多个文件的变更
test-driven-development	Red-Green-Refactor、测试金字塔（80/15/5）、测试规模、DAMP 优于 DRY、Beyoncé Rule、浏览器测试	实现逻辑、修 bug、改变行为
context-engineering	在对的时机喂给智能体对的信息：rules 文件、上下文打包、MCP 集成	会话开始、切换任务、输出质量下降
source-driven-development	每个框架决策都以官方文档为依据——验证、引用来源、标注未验证项	想要权威、带来源引用的框架代码
doubt-driven-development	对每个非平凡决策做对抗性新鲜上下文审查——CLAIM → EXTRACT → DOUBT → RECONCILE → STOP，可选用户授权的跨模型升级	高风险（生产、安全、不可逆）、陌生代码、或现在验证比日后调试便宜
frontend-ui-engineering	组件架构、设计系统、状态管理、响应式、WCAG 2.1 AA 可访问性	构建或修改用户可见界面
api-and-interface-design	契约先行设计、Hyrum's Law、One-Version Rule、错误语义、边界校验	设计 API、模块边界或公共接口

Verify —— 证明它可用

技能	作用	适用时机
browser-testing-with-devtools	Chrome DevTools MCP 获取实时运行时数据——DOM 检查、console 日志、网络追踪、性能剖析	构建或调试任何运行在浏览器里的东西
debugging-and-error-recovery	五步分诊：复现、定位、缩小、修复、守护；拉停线（stop-the-line）规则、安全回退	测试失败、构建破坏、行为异常

Review —— 合并前的质量门禁

技能	作用	适用时机
code-review-and-quality	五轴评审、变更规模（约 100 行）、严重度标签（Nit/Optional/FYI）、评审速度规范、拆分策略	任何变更合并前
code-simplification	Chesterton's Fence、Rule of 500，在保持行为完全一致的前提下降复杂度	代码能跑但比应有的更难读难维护
security-and-hardening	OWASP Top 10 预防、认证模式、密钥管理、依赖审计、三层边界体系	处理用户输入、认证、数据存储、外部集成
performance-optimization	度量优先——Core Web Vitals 目标、剖析工作流、bundle 分析、反模式识别	存在性能需求或怀疑回归

Ship —— 有把握地部署

技能	作用	适用时机
git-workflow-and-versioning	主干开发、原子提交、变更规模（约 100 行）、commit-as-save-point 模式	做任何代码变更（始终）
ci-cd-and-automation	Shift Left、Faster is Safer、特性开关、质量门禁流水线、失败反馈回路	搭建或修改构建/部署流水线
deprecation-and-migration	代码即负债心态、强制 vs 建议弃用、迁移模式、僵尸代码清理	移除旧系统、迁移用户、下线功能
documentation-and-adrs	架构决策记录、API 文档、行内文档标准——记录 why	架构决策、变更 API、发布功能
observability-and-instrumentation	结构化日志、RED 指标、OpenTelemetry 追踪、基于症状的告警——边构建边插桩	加遥测，或发布任何跑在生产的东西
shipping-and-launch	发布前清单、特性开关生命周期、灰度发布、回滚程序、监控搭建	准备部署到生产

五、元技能如何路由：`using-agent-skills` 的源码级细节

using-agent-skills 是整个技能包的路由中枢。它的 SKILL.md 内含一张任务分诊流程图，把 incoming 任务映射到具体技能：

Task arrives
    ├── Don't know what you want yet? ──────→ interview-me
    ├── Have a rough concept, need variants? → idea-refine
    ├── New project/feature/change? ──→ spec-driven-development
    ├── No quality bar written down? ──→ constraint-driven-development
    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
    ├── Implementing code? ────────────→ incremental-implementation
    │   ├── UI work? ─────────────────→ frontend-ui-engineering
    │   ├── API work? ────────────────→ api-and-interface-design
    │   ├── Need better context? ─────→ context-engineering
    │   ├── Need doc-verified code? ───→ source-driven-development
    │   └── Stakes high / unfamiliar code? ──→ doubt-driven-development
    ├── Writing/running tests? ────────→ test-driven-development
    ├── Something broke? ──────────────→ debugging-and-error-recovery
    ├── Reviewing code? ───────────────→ code-review-and-quality
    ├── Committing/branching? ─────────→ git-workflow-and-versioning
    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
    └── Deploying/launching? ─────────→ shipping-and-launch

同一个文件还定义了六条全程生效的核心操作行为（non-negotiable）：显式暴露假设（"ASSUMPTIONS I'M MAKING"）、主动管理困惑（STOP → 命名困惑 → 给出权衡 → 等待解决）、必要时反驳（不是 yes-machine，反对奉承）、强制简单（"如果 1000 行而 100 行就够，你就失败了"）、范围纪律（只动被要求动的）、验证而非假设（"Seems right" 永远不够，必须有测试输出/构建产物/运行时数据作为证据）。

对于完整功能，典型的技能序列是：

1.  interview-me → 2. idea-refine → 3. spec-driven-development
4.  planning-and-task-breakdown → 5. context-engineering
6.  source-driven-development → 7. incremental-implementation
8.  observability-and-instrumentation（与 7–9 并行，而非事后）
9.  doubt-driven-development → 10. test-driven-development
11. code-review-and-quality → 12. code-simplification
13. git-workflow-and-versioning → 14. documentation-and-adrs
15. deprecation-and-migration → 16. shipping-and-launch

并非每个任务都需要每个技能——一个 bug 修复可能只需要 debugging-and-error-recovery → test-driven-development → code-review-and-quality。

六、技能解剖：SKILL.md 的标准结构与上下文经济学

每个技能遵循一致的结构（README 中的解剖图）：

┌─────────────────────────────────────────────────┐
│  SKILL.md                                       │
│                                                 │
│  ┌─ Frontmatter ─────────────────────────────┐  │
│  │ name: lowercase-hyphen-name               │  │
│  │ description: Guides agents through [task].│  │
│  │              Use when…                    │  │
│  └───────────────────────────────────────────┘  │
│  Overview         → What this skill does        │
│  When to Use      → Triggering conditions       │
│  Process          → Step-by-step workflow       │
│  Rationalizations → Excuses + rebuttals         │
│  Red Flags        → Signs something's wrong     │
│  Verification     → Evidence requirements       │
└─────────────────────────────────────────────────┘

以 skills/test-driven-development/SKILL.md 为例可以看到这套结构如何落地：frontmatter 的 description 同时说明技能做什么（"Drives development with tests"）与何时触发（"Use when implementing any logic, fixing any bug, or changing any behavior"）；正文有 RED→GREEN→REFACTOR 循环图与 TypeScript 代码示例，还有 "The Prove-It Pattern"（修 bug 前先写复现测试）这样的具体流程。值得注意的是该技能还要求先探测项目自身工具链——通过 package.json/Cargo.toml/pyproject.toml 等判断测试命令，"绝不默认 npm test"——这正是"过程而非空谈"的体现。

关键设计决策：

过程，而非散文。 技能是智能体跟随的工作流，不是供其阅读的参考文档。每个技能都有步骤、检查点与退出标准。
反合理化。 每个技能都包含一张表格，列出智能体跳过步骤的常见借口（如 "I'll add tests later"）及成文的反驳论据——这是技能包最具辨识度的设计。
验证不可妥协。 每个技能以证据要求收尾：测试通过、构建输出、运行时数据。"看起来对"永远不够。
渐进式披露。 SKILL.md 是入口点，支撑性引用材料仅在需要时加载，保持 token 开销最小。

docs/skill-anatomy.md 给出了完整的格式规范，几条关键规则值得单独强调：

Frontmatter 规则：name 必须小写连字符且与目录名一致；description 最多 1024 字符，必须先说技能做什么（第三人称）再给 "Use when" 触发条件。原因是：智能体靠读 description 发现技能，它会被注入系统提示词，必须同时回答 what 和 when；不要在 description 里总结工作流，否则智能体可能跟随摘要而不读完整技能。
上下文效率：技能按需加载——启动时只有名称和描述在上下文中，完整 SKILL.md 仅在智能体判定相关时才加载。为此：保持 SKILL.md 在 500 行以内；文件引用保持一层深（SKILL.md 直连支撑文件，不链式经过中间文档）；优先脚本而非内联代码——执行脚本不消耗上下文，只有其输出消耗，而内联代码块在每次加载时都要"付费"。
脚本约定：技能自带的可运行助手（如 skills/idea-refine/scripts/idea-refine.sh）要求 #!/bin/bash shebang、set -e 快速失败、状态消息写 stderr、机器可读的 JSON 写 stdout、临时文件清理 trap。
共享引用 vs 自包含引用：多个技能共用的清单（测试、安全、性能、可访问性、DoD）放在仓库根 references/，这是包级设计选择——避免"复制进每个技能"或"指定一个技能独占"两种都会随时间漂移的方案；代价即前述单技能安装的可移植性问题（issue #361）。新近约定是：自包含可分发技能把自己的引用放在 skills/<name>/references/ 内（例如 skills/constraint-driven-development/references/floor-guard.md）。

七、斜杠命令之外的编排：`/ship` 的并行扇出模型

commands/ship.toml 展示了技能、命令与角色（persona）如何组合成一个高级工作流。/ship 是一个扇出编排器，分三个阶段：

Phase A —— 并行扇出：在主智能体的同一轮中并行派发三个子智能体（code-reviewer、security-auditor、test-engineer）——顺序调用会失去并行价值。子智能体运行在隔离的上下文循环中，只把报告返回主会话，且 persona 之间互不调用（保持扇出扁平）。
Phase B —— 主上下文合并：主智能体（而非子 persona）汇总代码质量、安全（Critical/High 发现升级为发布阻断项）、性能、可访问性、基础设施与文档六个维度。
Phase C —— 决策与回滚：产出单一的 GO | NO-GO 决策，含阻断项、建议修复、已知风险与强制的回滚计划（触发条件、回滚步骤、恢复时间目标）。任何 persona 返回 Critical 发现时，默认结论是 NO-GO。

它甚至规定了何时可以跳过扇出：仅当变更 ≤2 个文件、diff <50 行、且不触碰 auth/支付/数据访问/配置时才允许跳过。这套"人设不召唤人设"（personas don't invoke personas）的规则在 references/orchestration-patterns.md 中有完整说明。

八、Agent 人设：四位专家

agents/ 目录提供预配置的专家人设，用于定向评审（CLI 会将每个 agents/<name>.md 暴露为同名工具，支持 @code-reviewer 显式调用）：

Agent	角色	视角
code-reviewer	Senior Staff Engineer	五轴代码评审，"staff 工程师会批准这个吗"标准
test-engineer	QA 专家	测试策略、覆盖分析、Prove-It 模式
security-auditor	安全工程师	漏洞检测、威胁建模、OWASP 评估
web-performance-auditor	Web 性能工程师	Core Web Vitals 审计，Quick/Deep 双模式与"指标诚实"规则；经 `/webperf` 运行

从 agents/code-reviewer.md 源码可以看到，其五维评审（正确性、可读性、架构、安全、性能）每维都列出了具体检查点（如 N+1 查询、参数化查询、循环依赖），并沿用 code-review-and-quality 技能的严重度标签体系：Critical（阻断合并）、Required（合并前必须处理）、Optional（值得考虑）、Nit（可忽略的小问题）。角色定义与技能、命令的组合方式及决策矩阵见 docs/agents.md。

九、共享参考清单

技能按需拉取的快速参考材料（仓库根 references/，共 7 份）：

参考	内容
references/definition-of-done.md	项目级常设质量底线（与每任务验收标准对照）
references/testing-patterns.md	测试结构、命名、mock、React/API/E2E 示例、反模式（JS/TS）
references/security-checklist.md	提交前检查、认证、输入校验、响应头、CORS、OWASP Top 10
references/performance-checklist.md	Core Web Vitals 目标、前后端清单、度量命令
references/accessibility-checklist.md	键盘导航、屏幕阅读器、视觉设计、ARIA、测试工具
references/observability-checklist.md	On-call 问题、结构化日志、RED/USE 指标、追踪、症状告警、发布前门禁
references/orchestration-patterns.md	被认可的多人设编排模式、反模式、"人设不调用人设"规则

十、仓库结构

agent-skills/
├── skills/                            # 25 个技能（24 生命周期 + 1 元技能）
│   ├── interview-me/                  #   Define
│   ├── idea-refine/                   #   Define
│   ├── spec-driven-development/       #   Define
│   ├── constraint-driven-development/ #   Define
│   ├── planning-and-task-breakdown/   #   Plan
│   ├── incremental-implementation/    #   Build
│   ├── context-engineering/           #   Build
│   ├── source-driven-development/     #   Build
│   ├── doubt-driven-development/      #   Build
│   ├── frontend-ui-engineering/       #   Build
│   ├── test-driven-development/       #   Build
│   ├── api-and-interface-design/      #   Build
│   ├── browser-testing-with-devtools/ #   Verify
│   ├── debugging-and-error-recovery/  #   Verify
│   ├── code-review-and-quality/       #   Review
│   ├── code-simplification/           #   Review
│   ├── security-and-hardening/        #   Review
│   ├── performance-optimization/      #   Review
│   ├── git-workflow-and-versioning/   #   Ship
│   ├── ci-cd-and-automation/          #   Ship
│   ├── deprecation-and-migration/     #   Ship
│   ├── documentation-and-adrs/        #   Ship
│   ├── observability-and-instrumentation/ # Ship
│   ├── shipping-and-launch/           #   Ship
│   └── using-agent-skills/            #   Meta：如何使用本技能包
├── agents/                            # 4 个专家人设
├── references/                        # 7 份补充清单
├── hooks/                             # 会话生命周期钩子
├── .claude/commands/                  # 斜杠命令（Claude Code）
├── .gemini/commands/                  # 斜杠命令（Gemini CLI）
├── commands/                          # 斜杠命令（Antigravity CLI，TOML）
├── plugin.json                        # Antigravity 插件清单
└── docs/                              # 各工具安装指南

几个值得留意的实现细节：

plugin.json 是 Antigravity 插件清单，当前版本 0.6.8，声明 name: agent-skills 与项目描述。
hooks/hooks.json 注册了 SessionStart 钩子，会话开始时执行 hooks/session-start.sh（带 ${CLAUDE_PLUGIN_ROOT} 与项目目录双路径回退，失败时 || true 不阻塞会话）。
evals/ 目录包含每个技能一个的评测用例（evals/cases/<skill-name>.json，共 25 个）与对应的 evals/fixtures/ 项目级 fixture——技能不是写完就算，而是持续被"考试"。

十一、技能如何被验证：三层评测体系

evals/README.md 描述了本仓库如何度量技能是否真的有效——该在何时触发、彼此保持区分、并如承诺的那样改变智能体行为。体系分三层：

层级	检查什么	运行方式	成本
1. 结构	frontmatter、命名、必需章节、命令一致性	CI（`validate-skills.js`、`validate-commands.js`）	免费
2. 触发与路由	正向 prompt 让本技能排 top-k；负向 prompt 不排；任意两个描述不近撞	CI（`run-evals.js`）	免费
3. 行为	跟随技能的智能体满足其 `expectations[]`	按需（`run-evals.js --behavioral`）	消耗 token

运行方式：

# Tier 2 — 确定性，跑在 CI 中
node scripts/run-evals.js
node scripts/run-evals.js --min-rank1 80  # enforce the current routing floor

# Tier 3 — 行为级，headless claude 逐条跑评测再评分
node scripts/run-evals.js --behavioral test-driven-development            # 消耗 token
node scripts/run-evals.js --behavioral test-driven-development --dry-run  # 只打印计划

关键机制值得展开：

Tier 2 是路由的词法近似（对描述做词干化 TF-IDF）。它判断不了语义——那是 Tier 3 的事——但能抓住真实触发 bug 的两大模式：描述缺少用户实际使用的词汇（假阴性），以及描述过宽压过正确技能（假阳性）。Tier-2 失败通常意味着改描述，而不是改评测。
评测用例格式（evals/cases/test-driven-development.json 为代表）：trigger 块含 positive（应路由到本技能的真实用户话术，top_k 默认 3，签名式请求可收紧到 1）与 negative（属于其他技能的 prompt，声明 owner 后运行器会断言 owner 排在本技能之前，避免"什么都不匹配就空过"的假通过）；evals[] 块沿用 skill-creator 的 id/prompt/expected_output/files[]/expectations[] 模式，外加本仓库的 kind 字段（execution 默认 / dialogue）。
行为级执行环境：execution 类评测在一次性 git 仓库中运行，evals/fixtures/ 的真实项目输入被物化并作为基线提交；执行器使用显式权限模式（--permission-mode acceptEdits + 预批准工具清单），让执行评测真正能改文件、跑命令、看 diff、做提交，而不是被拒绝后"口头描述"。执行轨迹被围栏为不可信数据、经 stdin 管道送入评分器（可能达数 MB，argv 会撞操作系统参数长度限制），评分输出先验证 JSON 合法性再写入 evals/results/。纪律类技能还包含压力用例（时间压力、沉没成本、权威压力），验证当 prompt 主张跳过流程时工作流依然成立。
关注指标：Tier-2 输出 trigger rank-1 rate（正向 prompt 中排第一的占比，而非仅 top-k）。CI 以 --min-rank1 80 运行，低于已入库 86% 基线留出余量；描述两两相似度 ≥75% 报错、≥50% 警告。已知描述词汇缺口被跟踪在 issue #351。

结构性校验脚本位于 scripts/validate-skills.js、scripts/validate-commands.js，路由评测位于 scripts/run-evals.js（配套自测文件如 scripts/run-evals-test.js 保证评测框架本身也被测试）。

十二、落地路径：绿地 vs 存量代码库

安装之后，如何铺开取决于代码库所处阶段。docs/adoption-guide.md 给出两条路径：

路径 A —— 绿地（Greenfield）：从第一天跑完整生命周期

/spec   →  SPEC.md            (spec-driven-development)
/plan   →  tasks/plan.md      (planning-and-task-breakdown)
/build  →  one slice at a time (incremental-implementation + test-driven-development)
/review →  before every merge  (code-review-and-quality)
/ship   →  when going live     (shipping-and-launch)

Day 0 三件事：安装技能包；加载 using-agent-skills 元技能让智能体自主路由；添加一份简短的项目规则文件（CLAUDE.md 等），context-engineering 描述了其中应放什么。从第一天常开的技能：TDD（覆盖率债务在零时最便宜）、git 纪律（约 100 行的原子提交是习惯而非 retrofit）、安全加固（认证/输入校验/密钥是结构性的）、文档与 ADR（最早的架构决策恰恰是两年后没人记得 why 的那些）。典型反模式：以"这只是原型"为由跳过 /spec（原型会变产品）、一次往每个会话塞全部 25 个技能（浪费上下文、稀释重点）、把可观测性推迟到"有东西可观测时"。

路径 B —— 存量（Brownfield）：增量、验证优先

风险画像反转：危险不是构建错了什么，而是改动了没人完整定义过行为的东西。采用顺序因此从"读取与保护"代码库的技能开始，再到"改变"它的技能：

Phase 1 —— 上下文与只读技能：context-engineering 先行（写代码中真实的约定，包括"别碰 legacy/billing，它没有测试且有三个已知 workaround"这类地雷）；code-review-and-quality 审查 incoming 变更（零风险、立即可用）；debugging-and-error-recovery 处理你本来就要修的 bug（其"guard"步骤开始建立缺失的回归套件）；doubt-driven-development 作为安全网（陌生代码 + 犯错成本高正是其目标场景）。
Phase 2 —— 变更之前先测试：test-driven-development 选择性应用——不求全局覆盖，只求变更计划触及之处有覆盖；对无测试的遗留行为先写特征化测试（characterization tests，钉住代码当前行为，对错都钉）；code-simplification 处理最差的热点（Chesterton's Fence：理解代码为何存在，再动它）；git 纪律在存量代码里更重要——约 100 行的提交可以 bisection，2000 行的"现代化"提交不行。
Phase 3 —— 新工作跑完整生命周期：双速采用——旧代码留在 Phase 1–2 制度下，新功能享受绿地待遇（/spec → /plan → /build → /review）；新旧代码交界处用 api-and-interface-design 契约先行（"Hyrum's Law 在多年代码库里不是理论问题，有人依赖每一个可观测行为——包括 bug"）。
Phase 4 —— 清偿、弃用、观测：deprecation-and-migration（收缩遗留面而非包裹它）、observability-and-instrumentation（沿你实际调试的路径 retrofit）、performance-optimization（度量优先规则防止优化从来不是瓶颈的代码）。

两条路径最终收敛于同一稳态：新工作跑 /spec → /plan → /build → /review → /ship，TDD 与 git 纪律常开，合并前有评审门禁，技能按阶段加载而非整包灌入。

十三、贡献指南与许可

贡献新技能需满足四个标准：specific（可执行步骤，而非模糊建议）、verifiable（带证据要求的清晰退出标准）、battle-tested（基于真实工作流）、minimal（只放引导智能体所需的内容）。完整格式规范见 docs/skill-anatomy.md，贡献流程见 CONTRIBUTING.md。

从仓库自身配置 CLAUDE.md 可以推断出维护纪律：新技能提交前需做 pre-flight 检查（搜索目录、查开放 PR、确认契合 skill-anatomy 规格、论证缺口存在），优先扩展现有技能而非新增近重复技能；PR 偏好小而聚焦，避免大范围重构 scripts/ 这类共享文件；技能间禁止重复内容，用引用替代。

evals/README.md 还规定：每个技能必须自带评测文件——新增 skills/<name>/ 时须添加 evals/cases/<name>.json，至少 3 个正向触发、2 个负向触发、1 个行为级评测；缺失用例文件、用例数不足、未知 kind、非法 fixture 路径都会成为 CI 错误。

许可协议为 MIT——可在你的项目、团队与工具中自由使用这些技能。