agent-skills 快速上手：把生产级工程技能装进你的 AI 编码 Agent

本篇指南基于 agent-skills 仓库的入门文档 docs/getting-started.md 展开，讲解如何把这套"生产级工程技能"（skills）加载到任意 AI 编码 Agent 中。读完后，你将掌握技能（Skill）的工作机制、四种通用加载方式、最小化与全生命周期两套落地方案，以及 agents 角色、斜杠命令、参考清单三类配套资产的使用方法，并理解仓库源码中各组件的实际调用关系。

技能如何工作：是流程，不是文档

agent-skills 适用于任何接受 Markdown 指令的 AI 编码 Agent。它的核心单元是技能（Skill），每个技能就是一个 Markdown 文件（SKILL.md），描述一条具体的工程工作流。当技能被加载进 Agent 的上下文后，Agent 会按流程执行——包括验证步骤、需要规避的反模式，以及明确的退出标准。

这里有一条关键认知（原文档加粗强调）：

技能不是参考文档（reference docs），而是 Agent 逐步执行的流程（step-by-step processes）。

从源码可以印证这一点。以 skills/test-driven-development/SKILL.md 的 frontmatter 为例：

---
name: test-driven-development
description: Drives development with tests. Use when implementing any logic, fixing any bug,
  or changing any behavior. Use when you need to prove that code works, when a bug report
  arrives, or when you're about to modify existing functionality.
---

name 与目录名一致（小写连字符命名），description 采用"第三人称说明技能做什么 + Use when 触发条件"的写法。这种 frontmatter 契约是技能被 Agent 自动发现的前提：Agent 启动时只把技能名和描述注入上下文，只有当 Agent 判断技能与当前任务相关时，才会加载完整的 SKILL.md。完整的格式规范见 docs/skill-anatomy.md。

快速开始：任意 Agent 的四步接入

第 1 步：克隆仓库

git clone https://gitcode.com/GitHub_Trending/agentskill/agent-skills

如果你只想要最快速的通用路径，也可以使用开源的 skills CLI 一条命令安装全部技能（见 README.md 的 Quick Start 章节）：

npx skills add addyosmani/agent-skills            # 安装全部 25 个技能
npx skills add addyosmani/agent-skills --list     # 安装前先浏览列表

适用前提：单技能安装（--skill <name>）只会拷贝 skills/<name>/ 目录本身，仓库根目录的共享 references/ 清单不会被带过去。技能本身仍可工作，但它指向的共享清单路径将不可用。建议整仓集成、克隆仓库，或把所需清单复制进已安装技能的 references/ 目录内。这个可移植性缺口在上游仓库以 Issue #361 跟踪。

第 2 步：选择一个技能

浏览 skills/ 目录，每个子目录都包含一个 SKILL.md，结构统一，包含五类要素：

• When to use（何时使用）——指示该技能适用的触发条件
• Process（流程）——逐步执行的工作流
• Verification（验证）——如何确认工作已完成
• Common rationalizations（常见自我合理化）——Agent 可能用来跳过步骤的借口及对应反驳
• Red flags（危险信号）——技能正在被违反的迹象

仓库当前共包含 25 个技能（24 个生命周期技能 + 1 个元技能），按阶段分组：Define（interview-me、idea-refine、spec-driven-development 等）、Plan（planning-and-task-breakdown）、Build（incremental-implementation、test-driven-development、frontend-ui-engineering 等）、Verify（browser-testing-with-devtools、debugging-and-error-recovery）、Review（code-review-and-quality、security-and-hardening 等）、Ship（git-workflow-and-versioning、ci-cd-and-automation、shipping-and-launch 等）。完整目录见 README.md 的 "All 24 Skills" 章节。

第 3 步：把技能加载进 Agent

把目标 SKILL.md 的内容复制进 Agent 的系统提示词、规则文件或对话中。最常见的三种方式：

• 系统提示词（System prompt）：在会话开始时粘贴技能内容。
• 规则文件（Rules file）：把技能内容写进项目的规则文件（CLAUDE.md、.cursorrules 等）。仓库自带的 CLAUDE.md 就是一个规则文件实例——不过它配置的是"在 agent-skills 仓库内部工作"的 Agent，文档明确提示不要把它复制到你的项目或全局配置里，可复用的资产是 skills/ 下的技能本身。
• 对话引用（Conversation）：在指令中引用技能，例如："Follow the test-driven-development process for this change."（对本次变更遵循 test-driven-development 流程。）

第 4 步：用元技能做技能发现

建议始终先加载 using-agent-skills 元技能。它内置了一张任务类型 → 技能的路由流程图，让 Agent 能自行判断当前任务该走哪条流程。从源码 skills/using-agent-skills/SKILL.md 可以看到其核心路由逻辑（节选）：

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
    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
    ├── Implementing code? ────────────→ incremental-implementation
    ├── Writing/running tests? ────────→ test-driven-development
    ├── Something broke? ──────────────→ debugging-and-error-recovery
    ├── Reviewing code? ───────────────→ code-review-and-quality
    ├── Committing/branching? ─────────→ git-workflow-and-versioning
    ├── Deploying/launching? ─────────→ shipping-and-launch
    └── ...（UI、API、CI/CD、文档、可观测性等分支，完整图见 SKILL.md）

该元技能还定义了六条"始终生效"的核心操作行为（显式暴露假设、主动管理困惑、必要时提出异议、强制简洁、范围纪律、验证而非假设）和 16 步完整生命周期序列（interview-me → spec → plan → context → build → 测试 → review → 简化 → git → 文档 → 发布），是理解整套技能如何协同的入口文档。

推荐配置：从最小集到全生命周期

最小集（建议从这里开始）

在真实项目中落地前，先把 3 个核心技能加载进规则文件：

1. spec-driven-development——定义"要构建什么"（先规格后代码）
2. test-driven-development——证明"它确实能工作"（测试即证据）
3. code-review-and-quality——合并前验证质量（五轴审查）

这三个技能覆盖了 AI 辅助开发中最关键的质量缺口。注意 skills/spec-driven-development/SKILL.md 的触发条件写得很明确："Use when starting a new project, feature, or significant change and no specification exists yet"（当开始新项目、新功能或重大变更且尚不存在规格说明时使用）。

全生命周期

需要全面覆盖时，按开发阶段加载技能：

项目启动:    spec-driven-development → planning-and-task-breakdown
开发过程中:  incremental-implementation + test-driven-development
合并之前:    code-review-and-quality + security-and-hardening
部署之前:    shipping-and-launch

上下文感知加载（Context-Aware Loading）

不要一次加载全部技能——那会白白消耗上下文，还会稀释真正重要的技能。按当前任务加载相关技能：

• 做 UI？加载 frontend-ui-engineering
• 在调试？加载 debugging-and-error-recovery
• 搭 CI？加载 ci-cd-and-automation

对于要在真实项目中推广的团队，仓库还提供了两条端到端路径的详细指南：绿地项目从零启用全生命周期，以及成熟代码库的"验证优先、渐进式"落地方案，见 docs/adoption-guide.md。

技能结构（Skill Anatomy）

每个技能都遵循相同的结构：

YAML frontmatter (name, description)
├── Overview — 这个技能做什么
├── When to Use — 触发条件
├── Core Process — 逐步工作流
├── Examples — 代码示例与模式
├── Common Rationalizations — 借口及反驳
├── Red Flags — 技能被违反的迹象
└── Verification — 退出标准清单

其中两个设计点值得特别强调（依据 docs/skill-anatomy.md 的完整规格）：

• 反合理化表（Common Rationalizations）：把 Agent 常说的"我待会儿再补测试""这很简单不用写规格"逐条列出并配上事实性反驳，防止 Agent 找借口跳过流程。
• 验证即不可谈判项：每个技能以带证据要求的清单收尾——测试通过、构建输出、运行时数据，"看起来对"永远不算数。

上下文效率也是结构约束的一部分：SKILL.md 建议控制在 500 行以内，超过 100 行的参考资料拆到支撑文件中按需加载；被多个技能共享的清单则统一放在仓库根目录的 references/ 下，作为唯一事实来源（pack 级设计选择，权衡与代价见 anatomy 文档的 "Shared References" 一节）。

使用 Agents：四个预置专家角色

agents/ 目录包含预配置的 Agent 角色（persona），用于专项审查：

Agent	用途
code-reviewer.md	五轴代码审查
test-engineer.md	测试策略与编写
security-auditor.md	漏洞检测
web-performance-auditor.md	Core Web Vitals 与性能审计（通过 /webperf 调用）

从源码看，每个角色文件同样是"frontmatter + 角色指令"的 Markdown 结构。以 agents/code-reviewer.md 为例，它定义了一位"Senior Staff Engineer"，要求按正确性、可读性、架构、安全、性能五个维度评估变更并给出分类反馈。使用方式：在需要专项审查时加载对应角色定义，例如要求编码 Agent"使用 code-reviewer 角色审查这次变更"，并把该角色文件一并提供。

使用 Commands：斜杠命令一览

仓库为 Claude Code 提供了斜杠命令，位于 .claude/commands/ 目录。命令与技能的映射关系如下：

命令	调用的技能
/spec	spec-driven-development
/plan	planning-and-task-breakdown
/build	incremental-implementation + test-driven-development
/build auto	planning-and-task-breakdown → incremental-implementation + test-driven-development（整个计划一次批准）
/test	test-driven-development
/review	code-review-and-quality
/code-simplify	code-simplification
/ship	shipping-and-launch
/webperf	web-performance-auditor（专家角色，仅限 Web 应用）

结合命令源码可以进一步理解几个命令的实际行为：

• .claude/commands/spec.md：先就目标用户、核心功能与验收标准、技术栈约束、边界（总是做/先问/绝不做）提问，再生成覆盖六大领域的结构化规格，保存为项目根目录的 SPEC.md 并与用户确认。
• .claude/commands/build.md：定义了两种模式。默认 /build 每次只实现计划中的下一个待办任务（读取验收标准 → 写失败测试 RED → 最小实现 GREEN → 全量回归 → 构建验证 → 提交 → 标记完成并停止）；/build auto 则在存在规格文件的前提下，对整个计划做一次人类批准，随后自主执行每个任务的完整测试驱动循环。关键约束：自主模式只移除"任务之间的人工步进"，不移除验证——每个任务仍须通过测试并单独提交；遇到测试无法通过、规格含糊、或高风险不可逆操作（认证变更、破坏性数据迁移、支付、删除、部署等）时，必须停下来询问用户。
• .claude/commands/ship.md：是一个"扇出编排器"——并行运行三个专家角色对当前变更做独立检查，再把报告合并成唯一的 go/no-go 决策与回滚方案。
• .claude/commands/webperf.md：明确限定只针对 Web 应用，不用于工具库、CLI 或无浏览器输出的纯服务端代码。

插件安装时的警告说明：作为 Claude Code 插件安装时，你可能看到类似 "Default commands/ folder is ignored because the manifest sets 'commands'" 的警告。这是预期行为：仓库根目录的 commands/ 目录属于 Antigravity CLI，与 .claude/commands/ 有意分开；所有 Claude Code 斜杠命令都正确地从 .claude/commands/ 加载，该警告纯属显示层面。插件清单见 plugin.json（当前版本 0.6.8）。

使用 References：补充清单

references/ 目录存放补充性检查清单，当技能本身覆盖的细节不够时按需加载：

Reference	配合使用的技能
testing-patterns.md	test-driven-development
performance-checklist.md	performance-optimization
security-checklist.md	security-and-hardening
accessibility-checklist.md	frontend-ui-engineering
definition-of-done.md	所有技能 / 每次变更
observability-checklist.md	observability-and-instrumentation
orchestration-patterns.md	doubt-driven-development

其中 references/definition-of-done.md 值得单独说明：它定义的是"每个变更都必须跨过的、项目级常设门槛"（测试通过、无回归、运行时行为已验证、文档已更新），与逐任务的验收标准互补——任务只有在其自身验收标准满足且常设 DoD 达标时才算完成。

再次强调前文提到的限制：单技能 npx 安装场景下，这些位于仓库根目录的共享清单路径不可用，需整仓集成或手动拷贝清单文件（缺口由上游 Issue #361 跟踪）。

Spec 与任务工件的管理

/spec 和 /plan 命令会产生工作工件（SPEC.md、tasks/plan.md、tasks/todo.md）。在工作进行期间，应把它们当作**活文档（living documents）**对待：

• 开发期间保留在版本控制中，让人与 Agent 拥有共享的单一事实来源；
• 范围或决策变化时同步更新；
• 如果你的仓库不希望这些文件长期存在，合并前删除或把相应目录加入 .gitignore——工作流并不要求它们永久存在。

/build auto 命令的源码（.claude/commands/build.md）也印证了这一点：自主模式会先检查 git status --porcelain 的干净基线，把计划文件作为独立预备提交，并严格按"只暂存该任务触碰的文件、每任务一次提交"执行，保证任何提交点都是干净的回滚位置。

实用建议（Tips）

入门文档最后给出的五条实践建议，按优先级：

1. 任何非平凡工作从 spec-driven-development 开始——规格是代码库中最廉价的工件；
2. 写代码时始终加载 test-driven-development——测试即证明；
3. 不要跳过验证步骤——它们是整套技能的立身之本；
4. 选择性加载技能——更多上下文并不总是更好；
5. 用 agents 角色做审查——不同视角能捕捉不同问题。

小结

agent-skills 的接入路径可以概括为：克隆仓库（或 npx skills add）→ 选择阶段对应的 SKILL.md → 通过系统提示词、规则文件或对话引用三种方式之一注入 Agent → 用 using-agent-skills 元技能做路由。配置上建议从 spec/TDD/审查三技能的最小集起步，再按阶段扩展到全生命周期；配合 agents/ 的四个专家角色、.claude/commands/ 的斜杠命令和 references/ 的共享清单，即可在任意接受 Markdown 指令的编码 Agent 中获得一致的工程纪律。各工具（Claude Code、Cursor、Gemini CLI、Codex、OpenCode 等）的原生集成细节，可进一步参阅 docs/ 下的各 setup 指南与 docs/adoption-guide.md。