agent-skills

Agent Skills

面向 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 个斜杠命令，映射到开发生命周期。每个命令会自动激活相应的技能。

你正在做的事	命令	关键原则
定义要构建什么	/spec	先写规格，再写代码
规划如何构建	/plan	小粒度、原子化任务
增量式构建	/build	一次只做一个切片
证明它有效	/test	测试即证明
合并前审查	/review	提升代码健康度
简化代码	/code-simplify	清晰优于巧妙
交付到生产环境	/ship	更快即更安全

技能也会根据你正在做的事情自动激活——设计 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

遇到 SSH 错误？ marketplace 通过 SSH 克隆仓库。如果你在 GitHub 上未设置 SSH 密钥，请 添加你的 SSH 密钥，或使用完整的 HTTPS URL 强制使用 HTTPS 克隆：

/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/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。

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 规则配置中。参见 docs/windsurf-setup.md。

OpenCode

通过 AGENTS.md 和 skill 工具实现基于代理的技能执行。

参见 docs/opencode-setup.md。

GitHub Copilot

使用 agents/ 中的代理定义作为 Copilot 角色，并将技能内容放入 .github/copilot-instructions.md。参见 docs/copilot-setup.md。

Kiro IDE & CLI Kiro 的技能存放于 ".kiro/skills/" 下，可存储在项目级或全局级。Kiro 也支持 Agents.md。参见 Kiro 文档：https://kiro.dev/docs/skills/ Codex / 其他 Agent（代理）

技能是纯 Markdown 格式——它们适用于任何接受系统提示或指令文件的代理。参见 docs/getting-started.md。

---

全部 20 项技能

上述命令是入口点。在底层，它们会激活以下 20 项技能——每项技能都是一个结构化的工作流，包含步骤、验证门禁和反合理化表。你也可以直接引用任意技能。

定义——澄清要构建什么

技能	作用	何时使用
idea-refine	结构化发散/收敛思维，将模糊想法转化为具体提案	你有一个粗糙的概念需要探索
spec-driven-development	在写任何代码之前，编写一份 PRD，涵盖目标、命令、结构、代码风格、测试和边界	开始新项目、新功能或重大变更

规划——分解任务

技能	作用	何时使用
planning-and-task-breakdown	将规格分解为小的、可验证的任务，包含验收标准和依赖排序	你有规格，需要可执行的单元

构建——编写代码

技能	作用	何时使用
incremental-implementation	薄垂直切片——实现、测试、验证、提交。特性开关、安全默认值、可回滚变更	任何涉及多个文件的变更
test-driven-development	红-绿-重构，测试金字塔（80/15/5），测试规模，DAMP 优于 DRY，Beyonce 规则，浏览器测试	实现逻辑、修复 bug 或改变行为
context-engineering	在正确的时间为代理提供正确的信息——规则文件、上下文打包、MCP 集成	开始会话、切换任务，或输出质量下降时
source-driven-development	将每个框架决策建立在官方文档之上——验证、引用来源、标记未验证内容	你希望为任何框架或库获得权威、来源引用的代码
frontend-ui-engineering	组件架构、设计系统、状态管理、响应式设计、WCAG 2.1 AA 无障碍标准	构建或修改面向用户的界面
api-and-interface-design	契约优先设计、Hyrum's Law、One-Version Rule、错误语义、边界验证	设计 API、模块边界或公共接口

验证——证明它能工作

技能	作用	何时使用
browser-testing-with-devtools	使用 Chrome DevTools MCP 获取实时运行时数据——DOM 检查、控制台日志、网络追踪、性能分析	构建或调试任何在浏览器中运行的内容
debugging-and-error-recovery	五步分类法：复现、定位、简化、修复、防护。停止线规则、安全回退	测试失败、构建中断或行为不符合预期

审查——合并前的质量门禁

技能	作用	何时使用
code-review-and-quality	五轴审查、变更大小（约 100 行）、严重性标签（Nit/Optional/FYI）、审查速度规范、拆分策略	合并任何变更之前
code-simplification	Chesterton's Fence、500 规则、在保持精确行为的同时降低复杂度	代码工作正常，但比应有的更难读或更难维护
security-and-hardening	OWASP Top 10 预防、身份验证模式、密钥管理、依赖审计、三层边界系统	处理用户输入、身份验证、数据存储或外部集成
performance-optimization	度量先行方法——Core Web Vitals 目标、性能分析工作流、打包分析、反模式检测	存在性能要求或怀疑有性能退化

交付——自信地部署

技能	作用	何时使用
git-workflow-and-versioning	基于主干开发、原子提交、变更大小（约 100 行）、将提交作为保存点的模式	进行任何代码变更（始终如此）
ci-cd-and-automation	左移、更快即更安全、特性开关、质量门禁流水线、失败反馈循环	设置或修改构建和部署流水线
deprecation-and-migration	代码即债务理念、强制性/建议性废弃、迁移模式、僵尸代码清理	移除旧系统、迁移用户或废弃功能
documentation-and-adrs	架构决策记录（ADR）、API 文档、内联文档标准——记录为什么	做出架构决策、修改 API 或交付功能
shipping-and-launch	发布前检查清单、特性开关生命周期、分阶段发布、回滚流程、监控设置	准备部署到生产环境

---

代理角色（Agent Personas）

预配置的专业角色，用于针对性审查：

代理	角色	视角
code-reviewer	高级首席工程师	五轴代码审查，标准是“首席工程师会批准这个吗？”
test-engineer	QA 专家	测试策略、覆盖率分析以及证明模式
security-auditor	安全工程师	漏洞检测、威胁建模、OWASP 评估

---

参考清单

技能在需要时可快速调用的参考材料：

参考	涵盖内容
testing-patterns.md	测试结构、命名、模拟、React/API/E2E 示例、反模式
security-checklist.md	提交前检查、身份验证、输入验证、HTTP 头、CORS、OWASP Top 10
performance-checklist.md	Core Web Vitals 目标、前端/后端清单、度量命令
accessibility-checklist.md	键盘导航、屏幕阅读器、视觉设计、ARIA、测试工具

---

技能的工作原理

每项技能都遵循一致的结构：

┌─────────────────────────────────────────────────┐
│  SKILL.md                                       │
│                                                 │
│  ┌─ 前置元数据 ──────────────────────────────┐  │
│  │ name: lowercase-hyphen-name               │  │
│  │ description: Guides agents through [task].│  │
│  │              Use when…                    │  │
│  └───────────────────────────────────────────┘  │                                                                                                
│  概述            → 该技能的作用                     │
│  何时使用        → 触发条件                        │
│  流程            → 分步工作流                      │
│  常见合理化     → 借口 + 反驳                     │
│  红旗            → 问题迹象                       │
│  验证            → 证据要求                       │
└─────────────────────────────────────────────────┘

关键设计选择：

• 流程，而非散文。 技能是代理遵循的工作流，而不是它们阅读的参考文档。每个技能都有步骤、检查点和退出标准。
• 反合理化。 每项技能都包含一张表格，列出代理常用于跳过步骤的常见借口（例如“我稍后再加测试”），并附带已记录的反驳论据。
• 验证不可妥协。 每项技能都以证据要求结束——测试通过、构建输出、运行时数据。“看起来正确”永远不够。
• 渐进式披露。 SKILL.md 是入口点。支持性引用仅在需要时加载，从而最小化 token 使用量。

---

项目结构

agent-skills/
├── skills/                            # 20 项核心技能（每个目录一个 SKILL.md）
│   ├── idea-refine/                   #   定义
│   ├── spec-driven-development/       #   定义
│   ├── planning-and-task-breakdown/   #   规划
│   ├── incremental-implementation/    #   构建
│   ├── context-engineering/           #   构建
│   ├── source-driven-development/     #   构建
│   ├── frontend-ui-engineering/       #   构建
│   ├── test-driven-development/       #   构建
│   ├── api-and-interface-design/      #   构建
│   ├── browser-testing-with-devtools/ #   验证
│   ├── debugging-and-error-recovery/  #   验证
│   ├── code-review-and-quality/       #   审查
│   ├── code-simplification/          #   审查
│   ├── security-and-hardening/        #   审查
│   ├── performance-optimization/      #   审查
│   ├── git-workflow-and-versioning/   #   交付
│   ├── ci-cd-and-automation/          #   交付
│   ├── deprecation-and-migration/     #   交付
│   ├── documentation-and-adrs/        #   交付
│   ├── shipping-and-launch/           #   交付
│   └── using-agent-skills/            #   元技能：如何使用这个技能包
├── agents/                            # 3 个专业角色
├── references/                        # 4 个补充检查清单
├── hooks/                             # 会话生命周期钩子
├── .claude/commands/                  # 7 个斜杠命令（Claude Code）
├── .gemini/commands/                  # 7 个斜杠命令（Gemini CLI）
└── docs/                              # 各工具的设置指南

---

为什么需要 Agent Skills？

AI 编码助手默认会选择最短路径——这往往意味着跳过规格、测试、安全审查以及那些使软件可靠的做法。Agent Skills 为代理提供了结构化的工作流，强制执行与高级工程师在生产代码中相同的纪律。

每项技能都封装了来之不易的工程判断：何时编写规格、测试什么、如何审查、以及何时交付。这些不是通用提示——它们是有观点、流程驱动的工作流，能将生产级质量的工作与原型级质量的工作区分开来。

技能融入了 Google 工程文化的最佳实践——包括来自《Software Engineering at Google》（Software Engineering at Google）和 Google 的 工程实践指南 中的概念。你会在 API 设计中看到 Hyrum's Law，在测试中看到 Beyonce 规则和测试金字塔，在代码审查中看到变更大小和审查速度规范，在简化中看到 Chesterton's Fence，在 git 工作流中看到基于主干开发，在 CI/CD 中看到左移和特性开关，以及一个专门的废弃技能将代码视为负债。这些不是抽象原则——它们直接嵌入到代理遵循的逐步工作流中。

---

贡献

技能应做到 具体（可操作的步骤，而非模糊建议）、可验证（明确的退出标准及证据要求）、经过实战检验（基于真实工作流）以及 最小化（仅包含指导代理所需的内容）。

格式规范参见 docs/skill-anatomy.md，贡献指南参见 CONTRIBUTING.md。

---

许可证

MIT —— 在你的项目、团队和工具中使用这些技能。