addyosmani/agent-skills：AI 编程 Agent 的生产级工程规范

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

8 个 slash commands，对应开发生命周期的各个阶段。每个命令自动激活相应的技能。

如果希望在 spec 存在后减少手动步骤？/build 会自动生成计划并在一次审批中实现所有任务——你只需审批一次计划，然后它就会自主运行。它消除的是任务之间的人工介入，而非验证：每个任务仍然是测试驱动的、单独提交的，遇到失败或风险步骤时它会暂停。

技能也会根据你的操作自动激活——设计 API 时触发 api-and-interface-design，构建 UI 时触发 frontend-ui-engineering，以此类推。

最快路径——任意 agent，一条命令。开放技能 CLI 可接入 70+ 个 agent（Claude Code、Cursor、Codex、Copilot、Cline 等）：

npx skills add addyosmani/agent-skills            # 安装全部 24 个技能
npx skills add addyosmani/agent-skills --list     # 安装前浏览

或获取单个技能：

npx skills add addyosmani/agent-skills --skill code-review-and-quality   # 合并前的五轴审查
npx skills add addyosmani/agent-skills --skill interview-me              # 需求追问，一次一个问题
npx skills add addyosmani/agent-skills --skill test-driven-development   # 红-绿-重构，强制执行

安装单个技能？每次 npx install 只会复制 skills/<name>/，不会复制仓库级别的 references/ 目录。技能本身仍然可用，但补充共享检查清单的路径将不可用。使用完整仓库集成、克隆仓库，或将所需检查清单复制到已安装技能内的 references/ 目录。这个可移植性缺口在 #361 中追踪。

偏好原生集成？选择你的工具。

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

SSH 错误？marketplace 通过 SSH 克隆仓库。如果你没有在 GitHub 上设置 SSH 密钥，可以添加 SSH 密钥，或使用完整 HTTPS URL 强制在 marketplace-add 步骤中使用 HTTPS 克隆：

/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills

如果 /plugin install 在 Windows 或 macOS 上仍然失败并显示 git@github.com: Permission denied (publickey)，推荐的解决方法是配置 Git 全局重写 GitHub SSH URL 为 HTTPS 用于子进程克隆：

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

git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

将工作流技能放在 .cursor/skills/（从 agent-skills/skills/ 同步），将简短策略放在 .cursor/rules/*.mdc——不要将完整技能粘贴到 rules 中。参见 docs/cursor-setup.md。

作为原生插件安装，支持技能、子代理和 slash commands。参见 docs/antigravity-setup.md。

从仓库安装：

agy plugin install https://github.com/addyosmani/agent-skills.git

从本地克隆安装：

git clone https://github.com/addyosmani/agent-skills.git
agy plugin install ./agent-skills

作为原生技能安装以实现自动发现，或添加到 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 rules 配置中。参见 docs/windsurf-setup.md。

通过 AGENTS.md 和 skill 工具使用 agent 驱动的技能执行。

参见 docs/opencode-setup.md。

使用 agents/ 中的 agent 定义作为 Copilot persona，在 .github/copilot-instructions.md 中放置技能内容。参见 docs/copilot-setup.md。

作为原生 Codex 插件安装（Codex CLI v0.122+）：

codex plugin marketplace add addyosmani/agent-skills

Codex 通过 .codex-plugin/plugin.json 直接读取根目录的 skills/。安装后，在聊天中通过 @ 调用技能（如 @spec-driven-development）。本地安装和故障排除参见 docs/codex-setup.md。

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

已经安装过了？你如何推送到代码库取决于你的代码库。采纳指南涵盖两条路径：对于新项目从第一天开始的完整生命周期，或对于已有代码库采用的增量式、验证优先的推广方式。

以上命令是入口。这个包共包含 24 个技能——23 个生命周期技能加 1 个使用代理技能（using-agent-skills）的元技能。每个技能都是有步骤、验证门控和反合理化表格的结构化工作流程。你也可以直接引用任何技能。

Meta - Discover which skill applies

Define - Clarify what to build

Build - Write the code

Verify - Prove it works

Review - Quality gates before merge

Ship - Deploy with confidence

预配置的专业评审 persona：

参见 docs/agents.md 获取决策矩阵、编排规则，以及 persona 如何与技能和 slash commands 组合。

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

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

┌─────────────────────────────────────────────────┐
│  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       │
└─────────────────────────────────────────────────┘

流程，而非论述。技能是 agent 遵循的工作流程，不是它们阅读的参考文档。每个技能都有步骤、检查点和退出标准。

反合理化。每个技能都包含一个表格，列出 agent 用来跳过步骤的常见借口（如"我稍后再加测试"），并附有文档化的反驳论据。

验证是不可妥协的。每个技能都以证据要求结束——测试通过、构建输出、运行时数据。"看起来对"永远不够。

渐进式披露。SKILL.md 是入口点。支持性参考资料只在需要时加载，将 token 使用量降至最低。

agent-skills/
├── skills/                            # 24 个技能（23 个生命周期 + 1 个元技能）
│   ├── interview-me/                  #   Define
│   ├── idea-refine/                   #   Define
│   ├── spec-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 个专业 persona
├── references/                        # 7 个补充检查清单
├── hooks/                             # 会话生命周期 hooks
├── .claude/commands/                  # 8 个 slash commands（Claude Code）
├── .gemini/commands/                  # 8 个 slash commands（Gemini CLI）
├── commands/                          # 8 个 slash commands（Antigravity CLI）
├── plugin.json                        # Antigravity 插件清单
└── docs/                              # 各工具的设置指南

AI 编程 agent 默认走最短路径——这往往意味着跳过 spec、测试、安全审查和使软件可靠的实践。Agent Skills 给 agent 提供了强制执行与资深工程师在生产代码中相同的纪律的结构化工作流程。

每个技能都编码了来之不易的工程判断：何时写 spec、测什么、怎么 review、何时 ship。这些不是通用提示词——而是那种固执己见的、流程驱动的工作流程，区分了生产级工作和原型级工作。

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

想知道这个与 Superpowers 或 Matt Pocock 的技能相比如何？参见 docs/comparison.md，了解三者如何不同以及何时使用哪个的诚实并排比较——包括一个受控的面对面实验链接。

技能应该是具体的（可操作的步骤，而非模糊的建议）、可验证的（有明确退出标准和证据要求）、经过实战检验的（基于真实工作流程），以及最小的（只包含引导 agent 所需的内容）。

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

agent-skills 由以下人员构建和维护：

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