面向 AI 编码代理的生产级工程技能包。
Skills 把资深工程师在构建软件时使用的工作流、质量门禁和最佳实践编码成结构化流程，并打包成 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 个 slash command，对应开发生命周期中的关键阶段。每个命令都会自动激活正确的 skills。
| 你正在做什么 | 命令 | 核心原则 |
|---|---|---|
| 明确要构建什么 | /spec |
先写规格，再写代码 |
| 规划怎么构建 | /plan |
小而原子的任务 |
| 增量实现 | /build |
一次只做一个切片 |
| 证明它能工作 | /test |
测试就是证据 |
| 合并前评审 | /review |
持续改善代码健康 |
| 简化代码 | /code-simplify |
清晰胜过炫技 |
| 发布到生产环境 | /ship |
越快越安全 |
Skills 也会根据你的实际任务自动激活。例如设计 API 会触发 api-and-interface-design，构建 UI 会触发 frontend-ui-engineering，依此类推。
Claude Code（推荐）
通过 Marketplace 安装：
/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-skillsCursor
把任意 SKILL.md 复制到 .cursor/rules/，或者直接引用整个 skills/ 目录。详见 docs/cursor-setup.md。
Gemini CLI
可以安装为原生 skills，用于自动发现；也可以写进 GEMINI.md，作为持久上下文。详见 docs/gemini-cli-setup.md。
gemini skills install https://github.com/addyosmani/agent-skills.gitWindsurf
把 skill 内容加入 Windsurf 的 rules 配置。详见 docs/windsurf-setup.md。
GitHub Copilot
可以把 agents/ 里的 agent 定义作为 Copilot persona，把 skill 内容放进 .github/copilot-instructions.md。详见 docs/copilot-setup.md。
Codex / 其他 Agent
Skills 本质上是普通 Markdown，因此任何支持系统提示词或指令文件的 agent 都能使用。详见 docs/getting-started.md。
上面的命令只是入口。底层真正生效的是这 19 个 skills，每个 skill 都是一套带步骤、验证门禁和反合理化表格的结构化工作流。你也可以直接引用任意 skill。
| Skill | 作用 | 适用场景 |
|---|---|---|
| idea-refine | 用结构化发散 / 收敛思考，把模糊想法变成具体提案 | 你只有一个粗糙概念，还需要探索 |
| spec-driven-development | 在写代码前先写 PRD，覆盖目标、命令、结构、代码风格、测试和边界 | 开始新项目、新功能或重大改动 |
| Skill | 作用 | 适用场景 |
|---|---|---|
| planning-and-task-breakdown | 把 spec 拆成小而可验证的任务，带验收标准和依赖顺序 | 你已经有 spec，需要落地成可实现单元 |
| Skill | 作用 | 适用场景 |
|---|---|---|
| incremental-implementation | 薄切片式实现：实现、测试、验证、提交。包含 feature flag、安全默认值和回滚友好策略 | 任何会改到多个文件的任务 |
| test-driven-development | Red-Green-Refactor、测试金字塔（80/15/5）、测试尺寸、DAMP over DRY、Beyonce Rule、浏览器测试 | 实现逻辑、修 bug 或修改行为 |
| context-engineering | 在正确时间给 agent 正确上下文，例如 rules files、context packing、MCP 集成 | 开新会话、切换任务，或输出质量下降 |
| frontend-ui-engineering | 组件架构、设计系统、状态管理、响应式设计、WCAG 2.1 AA 可访问性 | 构建或修改面向用户的界面 |
| api-and-interface-design | 契约优先设计、Hyrum's Law、One-Version Rule、错误语义和边界校验 | 设计 API、模块边界或公开接口 |
| Skill | 作用 | 适用场景 |
|---|---|---|
| browser-testing-with-devtools | 使用 Chrome DevTools MCP 获取真实运行时数据，例如 DOM、控制台、网络和性能轨迹 | 构建或调试任何运行在浏览器中的东西 |
| debugging-and-error-recovery | 五步分诊：复现、定位、缩减、修复、防复发。包含 stop-the-line 规则和安全兜底 | 测试失败、构建损坏，或行为异常 |
| Skill | 作用 | 适用场景 |
|---|---|---|
| code-review-and-quality | 五维评审、改动规模控制（约 100 行）、严重级别标记（Nit/Optional/FYI）、评审速度规范与拆分策略 | 合并任何改动之前 |
| code-simplification | Chesterton's Fence、500 规则，在保持行为不变的前提下降低复杂度 | 代码能跑，但读起来或维护起来太重 |
| security-and-hardening | OWASP Top 10 防护、认证模式、secrets 管理、依赖审计、三层边界系统 | 涉及用户输入、认证、数据存储或外部集成 |
| performance-optimization | 先测量再优化，包含 Core Web Vitals 目标、profiling 流程、bundle 分析与反模式检测 | 有性能要求，或怀疑性能回退 |
| Skill | 作用 | 适用场景 |
|---|---|---|
| git-workflow-and-versioning | Trunk-based development、原子提交、改动规模控制和 commit-as-save-point 模式 | 任何代码改动，始终适用 |
| ci-cd-and-automation | Shift Left、Faster is Safer、feature flag、质量门禁流水线和失败反馈闭环 | 配置或修改构建与部署流水线 |
| deprecation-and-migration | “代码是负债”的思维、强制 / 建议弃用、迁移模式和 zombie code 清理 | 移除旧系统、迁移用户或下线功能 |
| documentation-and-adrs | ADR、API 文档、内联文档标准，重点记录 why | 做架构决策、改 API 或发布功能 |
| shipping-and-launch | 发布前检查清单、feature flag 生命周期、渐进式发布、回滚预案和监控配置 | 准备部署到生产环境 |
预配置的专家 persona，适合做针对性评审：
| Agent | 角色 | 视角 |
|---|---|---|
| code-reviewer | 高级 / Staff 工程师 | 基于五个维度的代码评审，标准是“一个 Staff 会批准吗？” |
| test-engineer | QA / 测试工程师 | 测试策略、覆盖率分析和 Prove-It Pattern |
| security-auditor | 安全工程师 | 漏洞发现、威胁建模和 OWASP 评估 |
Skills 在需要时会加载这些速查资料：
| Reference | 覆盖内容 |
|---|---|
| testing-patterns.md | 测试结构、命名、mock、React/API/E2E 示例与反模式 |
| security-checklist.md | 提交前检查、认证、输入校验、响应头、CORS、OWASP Top 10 |
| performance-checklist.md | Core Web Vitals 目标、前后端检查清单和测量命令 |
| accessibility-checklist.md | 键盘导航、屏幕阅读器、视觉设计、ARIA 和测试工具 |
每个 skill 都遵循统一的结构：
┌─────────────────────────────────────────────┐
│ SKILL.md │
│ │
│ ┌─ Frontmatter ─────────────────────────┐ │
│ │ name: lowercase-hyphen-name │ │
│ │ description: Use when [trigger] │ │
│ └───────────────────────────────────────┘ │
│ │
│ 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 是 agent 要遵循的工作流，不是随手读的参考文档。每个 skill 都带步骤、检查点和退出条件。
- 反合理化设计。 每个 skill 都包含一张常见借口表，比如 “测试以后再补”，并给出明确反驳。
- 验证不可妥协。 每个 skill 最后都要求证据，例如测试通过、构建输出、运行时数据；“看起来对”永远不够。
- 渐进式披露。
SKILL.md是入口，支持性参考文档只在必要时加载，以控制 token 消耗。
agent-skills/
├── skills/ # 19 个核心技能，每个目录一个 SKILL.md
│ ├── idea-refine/ # Define
│ ├── spec-driven-development/ # Define
│ ├── planning-and-task-breakdown/ # Plan
│ ├── incremental-implementation/ # Build
│ ├── context-engineering/ # 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：如何使用整个技能包
├── agents/ # 3 个专家 persona
├── references/ # 4 个补充检查清单
├── hooks/ # 会话生命周期 hook
├── .claude/commands/ # 7 个 slash command
└── docs/ # 各工具的接入指南
AI 编码代理天然倾向于走最短路径，而最短路径通常意味着跳过 spec、测试、安全评审，以及那些让软件真正可靠的工程实践。Agent Skills 的作用，就是把这些纪律变成结构化工作流，让 agent 也能像资深工程师那样工作。
每个 skill 都编码了来之不易的工程判断：什么时候 该写 spec，什么 应该测试，如何 做 review，什么时候 才该发布。这不是通用 prompt，而是那种真正区分“生产级工作”和“原型级工作”的、带明确立场的流程设计。
这些 skills 也内置了大量 Google 工程文化中的最佳实践，包括 Software Engineering at Google 和 Google 的 engineering practices guide。你会在 API 设计里看到 Hyrum's Law，在测试里看到 Beyonce Rule 和测试金字塔，在 code review 里看到改动规模控制和评审速度规范，在简化代码时看到 Chesterton's Fence，在 git 工作流里看到 trunk-based development，在 CI/CD 里看到 Shift Left 和 feature flags，还会看到一个专门把“代码视为负债”的弃用技能。这些都不是抽象原则，而是被直接嵌进了 agent 要遵循的逐步工作流里。
新增 skill 应该满足四个标准：具体，也就是步骤可执行；可验证，也就是退出条件清晰并带证据要求；经过实战验证，基于真实工程流程；以及 最小化，只保留真正能引导 agent 的内容。
格式规范见 docs/skill-anatomy.md，贡献指南见 CONTRIBUTING.md。
MIT。你可以在自己的项目、团队和工具里使用这些 skills。