14 KiB
AI编程智能体工程技能包
AI编程 工程技能 开发流程 代码质量 最佳实践
Agent Skills
面向AI编程智能体的生产级工程技能包。
技能包封装了高级工程师在构建软件时使用的工作流、质量门控和最佳实践。这些技能经过打包，让AI智能体在开发的每个阶段都能始终如一地遵循它们。
定义 规划 构建 验证 审查 发布
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│ 想法 │ ───▶ │ 规格 │ ───▶ │ 代码 │ ───▶ │ 测试 │ ───▶ │ QA │ ───▶ │ 上线 │
│ 细化 │ │ PRD │ │ 实现 │ │ 调试 │ │ 门控 │ │ 发布 │
└──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘
/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（推荐）
市场安装：
/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。
Gemini CLI
作为原生技能安装以支持自动发现，或添加到 GEMINI.md 以获得持久上下文。参见 docs/gemini-cli-setup.md。
gemini skills install https://github.com/addyosmani/agent-skills.git
Windsurf
将技能内容添加到你的 Windsurf 规则配置中。参见 docs/windsurf-setup.md。
GitHub Copilot
使用 agents/ 中的智能体定义作为 Copilot 角色，并将技能内容添加到 .github/copilot-instructions.md。参见 docs/copilot-setup.md。
Codex / 其他智能体
技能是纯 Markdown 格式——适用于任何接受系统提示或指令文件的智能体。参见 docs/getting-started.md。
全部19个技能
上述命令是入口点。在底层，它们会激活这19个技能——每个技能都是包含步骤、验证门控和反理性化表格的结构化工作流。你也可以直接引用任意技能。
定义 - 明确要构建的内容
| 技能 | 功能 | 适用场景 |
|---|---|---|
| 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集成 | 开始会话、切换任务或输出质量下降时 |
| frontend-ui-engineering | 组件架构、设计系统、状态管理、响应式设计、WCAG 2.1 AA无障碍访问 | 构建或修改面向用户的界面 |
| api-and-interface-design | 契约优先设计、Hyrum定律、单版本规则、错误语义、边界验证 | 设计API、模块边界或公共接口 |
验证 - 证明功能正确
| 技能 | 功能 | 适用场景 |
|---|---|---|
| browser-testing-with-devtools | Chrome DevTools MCP获取实时运行时数据——DOM检查、控制台日志、网络追踪、性能分析 | 构建或调试任何在浏览器中运行的内容 |
| debugging-and-error-recovery | 五步分类：复现、定位、缩小、修复、防护。停线规则，安全回退 | 测试失败、构建失败或行为异常 |
审查 - 合并前的质量门控
| 技能 | 功能 | 适用场景 |
|---|---|---|
| code-review-and-quality | 五维审查，变更规模（约100行），严重性标签（Nit/Optional/FYI），审查速度规范，拆分策略 | 合并任何变更之前 |
| code-simplification | Chesterton围栏原则，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 | 架构决策记录、API文档、内联文档标准——记录"为什么" | 做出架构决策、变更API或发布功能 |
| shipping-and-launch | 上线前检查清单、功能标志生命周期、分阶段发布、回滚流程、监控设置 | 准备部署到生产环境 |
智能体角色
预配置的专家角色，用于针对性审查：
| 智能体 | 角色 | 视角 |
|---|---|---|
| code-reviewer | 高级Staff工程师 | 以"Staff工程师会批准吗？"为标准的五维代码审查 |
| test-engineer | QA专家 | 测试策略、覆盖率分析和Prove-It模式 |
| security-auditor | 安全工程师 | 漏洞检测、威胁建模、OWASP评估 |
参考检查清单
技能在需要时调用的快速参考资料：
| 参考 | 涵盖内容 |
|---|---|
| testing-patterns.md | 测试结构、命名、模拟、React/API/E2E示例、反模式 |
| security-checklist.md | 提交前检查、认证、输入验证、请求头、CORS、OWASP Top 10 |
| performance-checklist.md | Core Web Vitals目标、前后端检查清单、测量命令 |
| accessibility-checklist.md | 键盘导航、屏幕阅读器、视觉设计、ARIA、测试工具 |
技能的工作原理
每个技能遵循统一的结构：
┌─────────────────────────────────────────────┐
│ SKILL.md │
│ │
│ ┌─ 前置信息 ─────────────────────────────┐ │
│ │ name: 小写连字符名称 │ │
│ │ description: 在[触发条件]时使用 │ │
│ └───────────────────────────────────────┘ │
│ │
│ 概述 → 本技能的功能 │
│ 使用时机 → 触发条件 │
│ 流程 → 逐步工作流 │
│ 合理化借口 → 借口 + 反驳 │
│ 红旗信号 → 出问题的迹象 │
│ 验证 → 证明要求 │
└─────────────────────────────────────────────┘
关键设计选择：
- 流程而非散文。 技能是智能体遵循的工作流，而非参考文档。每个技能都有步骤、检查点和退出标准。
- 反理性化。 每个技能都包含一张常见借口表，列出智能体用来跳过步骤的理由（例如"我待会儿再加测试"）以及对应的反驳论据。
- 验证不可妥协。 每个技能以证明要求作为结尾——测试通过、构建输出、运行时数据。"看起来没问题"永远不够。
- 渐进式披露。
SKILL.md是入口点。支撑性参考资料仅在需要时加载，将token使用量保持在最低水平。
项目结构
agent-skills/
├── skills/ # 19个核心技能（每个目录含SKILL.md）
│ ├── idea-refine/ # 定义
│ ├── spec-driven-development/ # 定义
│ ├── planning-and-task-breakdown/ # 规划
│ ├── incremental-implementation/ # 构建
│ ├── context-engineering/ # 构建
│ ├── 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个斜杠命令
└── docs/ # 各工具的安装指南
为什么选择 Agent Skills？
AI编程智能体默认走最短路径——这通常意味着跳过规格文档、测试、安全审查，以及那些让软件可靠运行的实践。Agent Skills 为智能体提供结构化工作流，强制执行高级工程师在生产代码中所体现的同等纪律性。
每个技能都编码了来之不易的工程判断力：何时写规格，测试什么，如何审查，以及何时发布。这些不是通用提示——而是将生产级工作与原型级工作区分开来的、有主见的、流程驱动的工作流。
技能中融入了谷歌工程文化的最佳实践——包括《Software Engineering at Google》和谷歌工程实践指南中的概念。你会在API设计中找到Hyrum定律，在测试中找到Beyonce规则和测试金字塔，在代码审查中找到变更规模和审查速度规范，在简化中找到Chesterton围栏原则，在git工作流中找到主干开发，在CI/CD中找到左移原则和功能标志，以及一个专门将代码视为负债的废弃技能。这些不是抽象原则——它们直接嵌入到智能体遵循的逐步工作流中。
贡献指南
技能应当具体（可操作的步骤，而非模糊建议）、可验证（有明确退出标准和证明要求）、经过实战检验（基于真实工作流）且精简（只包含引导智能体所需的内容）。
格式规范参见 docs/skill-anatomy.md，贡献指南参见 CONTRIBUTING.md。
许可证
MIT——在你的项目、团队和工具中自由使用这些技能。