addyosmani/agent-skills
GitHub: addyosmani/agent-skills
为 AI 编码代理提供生产级工程技能的结构化工作流，强制实施资深工程师的规范与质量门禁。
Stars: 16340 | Forks: 2080
# 代理技能
**面向 AI 编码代理的生产级工程技能。**
技能编码了资深工程师在构建软件时使用的流程、质量门禁和最佳实践。这些技能被打包成一致的格式，使 AI 代理在开发的每个阶段都能遵循相同的规范。
```
DEFINE PLAN BUILD VERIFY REVIEW SHIP
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │ QA │ ───▶ │ Go │
│Refine│ │ PRD │ │ Impl │ │Debug │ │ Gate │ │ Live │
└──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘
/spec /plan /build /test /review /ship
```
## 命令
7 个斜杠命令，对应开发生命周期的不同阶段。每个命令会自动激活相应的技能。
| 你正在做的事 | 命令 | 关键原则 |
|-------------------|---------|---------------|
| 定义要构建的内容 | `/spec` | 先写规格再写代码 |
| 规划如何构建 | `/plan` | 小而原子的任务 |
| 逐步构建 | `/build` | 一次一个切片 |
| 证明它有效 | `/test` | 测试即证明 |
| 合并前审查 | `/review` | 改进代码健康度 |
| 简化代码 | `/code-simplify` | 清晰优于巧妙 |
| 发布到生产 | `/ship` | 越快越安全 |
技能也会根据你当前的工作自动激活——设计 API 会触发 `api-and-interface-design`，构建 UI 会触发 `frontend-ui-engineering`，以此类推。
## 快速开始
## 全部 20 项技能
上述命令是入口点。在底层，它们会激活以下 20 项技能——每一项都是一个包含步骤、验证门和反合理化表格的结构化工作流。你也可以直接引用任何技能。
### 定义——澄清要构建什么
| 技能 | 作用 | 使用时机 |
|-------|-------------|----------|
| [idea-refine](skills/idea-refine/SKILL.md) | 结构化发散/收敛思考，将模糊想法转化为具体提案 | 当你有一个粗糙概念需要探索时 |
| [spec-driven-development](skills/spec-driven-development/SKILL.md) | 在编写任何代码之前撰写 PRD，涵盖目标、命令、结构、代码风格、测试和边界 | 启动新项目、功能或重大变更时 |
### 计划——分解任务
| 技能 | 作用 | 使用时机 |
|-------|-------------|----------|
| [planning-and-task-breakdown](skills/planning-and-task-breakdown/SKILL.md) | 将规格分解为可验证的小任务，并按依赖关系排序 | 拥有规格并需要可实施单元时 |
### 构建——编写代码
| 技能 | 作用 | 使用时机 |
|-------|-------------|----------|
| [incremental-implementation](skills/incremental-implementation/SKILL.md) | 薄垂直切片——实现、测试、验证、提交。功能标志、安全默认值、回滚友好变更 | 任何涉及多个文件的变更 |
| [test-driven-development](skills/test-driven-development/SKILL.md) | 红—绿—重构，测试金字塔（80/15/5）、DAMP 优于 DRY、 Beyonce 规则、浏览器测试 | 实现逻辑、修复错误或变更行为时 |
| [context-engineering](skills/context-engineering/SKILL.md) | 在合适时机向代理提供正确信息——规则文件、上下文打包、MCP 集成 | 开始会话、切换任务或输出质量下降时 |
| [source-driven-development](skills/source-driven-development/SKILL.md) | 以官方文档为依据做出框架决策——验证、引用来源、标注未经验证的内容 | 你需要权威、带引用的框架或库代码时 |
| [frontend-ui-engineering](skills/frontend-ui-engineering/SKILL.md) | 组件架构、设计系统、状态管理、响应式布局、WCAG 2.1 AA 可访问性 | 构建或修改用户界面时 |
| [api-and-interface-design](skills/api-and-interface-design/SKILL.md) | 契约优先设计、Hyrum 法则、单版本规则、错误语义、边界验证 | 设计 API、模块边界或公共接口时 |
### 验证——证明它有效
| 技能 | 作用 | 使用时机 |
|-------|-------------|----------|
| [browser-testing-with-devtools](skills/browser-testing-with-devtools/SKILL.md) | Chrome DevTools MCP，用于实时运行时数据——DOM 检查、控制台日志、网络跟踪、性能分析 | 构建或调试任何在浏览器中运行的内容 |
| [debugging-and-error-recovery](skills/debugging-and-error-recovery/SKILL.md) | 五步法：重现、定位、简化、修复、防护。停止规则、安全回退 | 测试失败、构建中断或行为异常时 |
### 审查——合并前的质量门禁
| 技能 | 作用 | 使用时机 |
|-------|-------------|----------|
| [code-review-and-quality](skills/code-review-and-quality/SKILL.md) | 五轴审查，变更规模（约 100 行）、严重等级（Nit/Optional/FYI）、审查速度规范、拆分策略 | 合并任何变更前 |
| [code-simplification](skills/code-simplification/SKILL.md) | Chesterton's Fence、500 行规则，在保持行为不变的前提下降低复杂度 | 代码可用但可读或可维护性不足时 |
| [security-and-hardening](skills/security-and-hardening/SKILL.md) | OWASP Top 10 预防、认证模式、密钥管理、依赖审计、三层边界系统 | 处理用户输入、认证、数据存储或外部集成时 |
| [performance-optimization](skills/performance-optimization/SKILL.md) | 以测量为先——核心 Web 指标目标、分析流程、包分析、反模式检测 | 存在性能要求或怀疑存在回归时 |
### 发布——自信部署
| 技能 | 作用 | 使用时机 |
|-------|-------------|----------|
| [git-workflow-and-versioning](skills/git-workflow-and-versioning/SKILL.md) | 分支直开发、原子提交、变更规模（约 100 行）、提交即保存点模式 | 进行任何代码变更时（始终适用） |
| [ci-cd-and-automation](skills/ci-cd-and-automation/SKILL.md) | 左移测试、更快更安全、功能标志、质量门禁流水线、失败反馈回路 | 设置或修改构建与部署流水线时 |
| [deprecation-and-migration](skills/deprecation-and-migration/SKILL.md) | 代码即负债思维、强制与建议式弃用、迁移模式、僵尸代码清理 |移除旧系统、迁移用户或下线功能时 |
| [documentation-and-adrs](skills/documentation-and-adrs/SKILL.md) | 架构决策记录、API 文档、内联文档标准——记录“为什么”而非“是什么” | 做出架构决策、变更 API 或发布功能时 |
| [shipping-and-launch](skills/shipping-and-launch/SKILL.md) | 发布前检查清单、功能标志生命周期、分阶段发布、回滚流程、监控设置 | 准备部署到生产环境时 |
## 代理角色设定
针对特定审查场景的预配置专家角色：
| 角色 | 职责 | 视角 |
|-------|------|-------------|
| [code-reviewer](agents/code-reviewer.md) | 资深工程师 | 以“资深工程师是否会批准此代码”为标准进行五轴审查 |
| [test-engineer](agents/test-engineer.md) | QA 专家 | 测试策略、覆盖率分析、验证模式 |
| [security-auditor](agents/security-auditor.md) | 安全工程师 | 漏洞检测、威胁建模、OWASP 评估 |
## 参考检查清单
技能调用时快速查阅的参考资料：
| 参考文档 | 涵盖内容 |
|-----------|--------|
| [testing-patterns.md](references/testing-patterns.md) | 测试结构、命名、模拟、React/API/E2E 示例、反模式 |
| [security-checklist.md](references/security-checklist.md) | 提交前检查、认证、输入验证、头部、CORS、OWASP Top 10 |
| [performance-checklist.md](references/performance-checklist.md) | 核心 Web 指标目标、前后端检查清单、测量命令 |
| [accessibility-checklist.md](references/accessibility-checklist.md) | 键盘导航、屏幕阅读器、视觉设计、ARIA、测试工具 |
## 技能如何工作
每个技能遵循一致的结构：
```
┌─────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────┘
```
**关键设计决策：**
- **流程而非文档。** 技能是代理遵循的工作流，而不是它们阅读的参考文档。每个技能都有步骤、检查点和退出标准。
- **反合理化。** 每个技能都包含一个表格，列出代理用来跳过步骤的常见借口（例如“我稍后会添加测试”）以及有记录的反驳理由。
- **验证不可协商。** 每个技能都以证据要求结束——测试通过、构建输出、运行时数据。“看起来正确”永远不够。
- **渐进式披露。** `SKILL.md` 是入口点。仅在需要时加载支持性参考，以保持令牌使用量最小。
## 项目结构
```
agent-skills/
├── skills/ # 20 core skills (SKILL.md per directory)
│ ├── idea-refine/ # Define
│ ├── spec-driven-development/ # Define
│ ├── planning-and-task-breakdown/ # Plan
│ ├── incremental-implementation/ # Build
│ ├── context-engineering/ # Build
│ ├── source-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
│ ├── shipping-and-launch/ # Ship
│ └── using-agent-skills/ # Meta: how to use this pack
├── agents/ # 3 specialist personas
├── references/ # 4 supplementary checklists
├── hooks/ # Session lifecycle hooks
├── .claude/commands/ # 7 slash commands
└── docs/ # Setup guides per tool
```
## 为何使用代理技能？
AI 编码代理默认选择最短路径——这通常意味着跳过规格、测试、安全审查以及使软件可靠的最佳实践。代理技能为代理提供了结构化流程，强制实施资深工程师在生产代码中带来的纪律。
每项技能都编码了来之不易的工程判断：*何时* 编写规格、*什么* 需要测试、*如何* 审查、*何时* 发布。这些不是通用提示——它们是嵌入在逐步工作流中的有观点、流程驱动的工作方式，将生产级工作与原型级工作区分开来。
技能将 Google 工程文化中的最佳实践融入其中——包括 [Google 软件工程](https://abseil.io/resources/swe-book) 和 [Google 工程实践指南](https://google.github.io/eng-practices/) 中的概念。你会在其中找到 API 设计中的 Hyrum 法则、测试中的 Beyonce 规则与测试金字塔、代码审查中的变更规模与审查速度规范、简化中的 Chesterton's Fence、分支直开发、CI/CD 中的左移和特性标志，以及专门用于处理代码负债的特性弃用技能。这些不是抽象原则——它们直接嵌入代理遵循的逐步工作流中。
## 贡献
技能应具备：
- **具体性**（可操作的步骤，而非模糊建议）
- **可验证性**（明确的退出标准与证据要求）
- **经过实战检验**（基于真实工作流）
- **精简性**（仅提供引导代理所需的内容）
参见 [docs/skill-anatomy.md](docs/skill-anatomy.md) 了解格式规范，参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
## 许可证
MIT —— 在你的项目、团队和工具中使用这些技能。
Claude Code（推荐）
**在市场安装：** ``` /plugin marketplace add addyosmani/agent-skills /plugin install agent-skills@addy-agent-skills ``` **本地 / 开发环境：** ``` git clone https://github.com/addyosmani/agent-skills.git claude --plugin-dir /path/to/agent-skills ```Cursor
将任意 `SKILL.md` 复制到 `.cursor/rules/`，或引用完整的 `skills/` 目录。参见 [docs/cursor-setup.md](docs/cursor-setup.md)。Gemini CLI
安装为原生技能以实现自动发现，或添加到 `GEMINI.md` 以保持持久上下文。参见 [docs/gemini-cli-setup.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 规则配置中。参见 [docs/windsurf-setup.md](docs/windsurf-setup.md)。OpenCode
通过 AGENTS.md 和 `skill` 工具使用代理驱动的技能执行。参见 [docs/opencode-setup.md](docs/opencode-setup.md)。GitHub Copilot
将 `agents/` 中的代理定义用作 Copilot 人设，并将技能内容放入 `.github/copilot-instructions.md`。参见 [docs/copilot-setup.md](docs/copilot-setup.md)。Kiro IDE & CLI
技能位于 ".kiro/skills/" 下，可存储在项目或全局级别。Kiro 也支持 Agents.md。详见 Kiro 文档：https://kiro.dev/docs/skills/Codex / 其他代理
技能是纯 Markdown，任何接受系统提示或指令文件的代理均可使用。参见 [docs/getting-started.md](docs/getting-started.md)。标签：AI 编程代理, API 设计, Claude Code, SEO: AI 编码代理, SEO: 生产级工程, Slash 命令, Spec 先行, 代码审查, 代码简化, 代码质量门禁, 前端工程, 功能: 工作流管理, 功能: 质量保障, 原子任务, 增量构建, 开发工作流, 快速部署, 技术栈: 工程化, 持续交付, 数据管道, 最佳实践, 测试驱动, 生产级工程技能, 网络安全研究, 软件工程, 防御加固