267 lines
14 KiB
Markdown
267 lines
14 KiB
Markdown
# 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`，依此类推。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
<details>
|
||
<summary><b>Claude Code（推荐）</b></summary>
|
||
|
||
**市场安装：**
|
||
|
||
```
|
||
/plugin marketplace add addyosmani/agent-skills
|
||
/plugin install agent-skills@addy-agent-skills
|
||
```
|
||
|
||
**本地/开发：**
|
||
|
||
```bash
|
||
git clone https://github.com/addyosmani/agent-skills.git
|
||
claude --plugin-dir /path/to/agent-skills
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Cursor</b></summary>
|
||
|
||
将任意 `SKILL.md` 复制到 `.cursor/rules/`，或引用完整的 `skills/` 目录。参见 [docs/cursor-setup.md](docs/cursor-setup.md)。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Gemini CLI</b></summary>
|
||
|
||
作为原生技能安装以支持自动发现，或添加到 `GEMINI.md` 以获得持久上下文。参见 [docs/gemini-cli-setup.md](docs/gemini-cli-setup.md)。
|
||
|
||
```bash
|
||
gemini skills install https://github.com/addyosmani/agent-skills.git
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Windsurf</b></summary>
|
||
|
||
将技能内容添加到你的 Windsurf 规则配置中。参见 [docs/windsurf-setup.md](docs/windsurf-setup.md)。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>GitHub Copilot</b></summary>
|
||
|
||
使用 `agents/` 中的智能体定义作为 Copilot 角色，并将技能内容添加到 `.github/copilot-instructions.md`。参见 [docs/copilot-setup.md](docs/copilot-setup.md)。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Codex / 其他智能体</b></summary>
|
||
|
||
技能是纯 Markdown 格式——适用于任何接受系统提示或指令文件的智能体。参见 [docs/getting-started.md](docs/getting-started.md)。
|
||
|
||
</details>
|
||
|
||
---
|
||
|
||
## 全部19个技能
|
||
|
||
上述命令是入口点。在底层，它们会激活这19个技能——每个技能都是包含步骤、验证门控和反理性化表格的结构化工作流。你也可以直接引用任意技能。
|
||
|
||
### 定义 - 明确要构建的内容
|
||
|
||
| 技能 | 功能 | 适用场景 |
|
||
|------|------|----------|
|
||
| [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规则，浏览器测试 | 实现逻辑、修复Bug或变更行为 |
|
||
| [context-engineering](skills/context-engineering/SKILL.md) | 在正确的时间向智能体提供正确的信息——规则文件、上下文打包、MCP集成 | 开始会话、切换任务或输出质量下降时 |
|
||
| [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围栏原则，500行规则，在保持行为完全不变的前提下降低复杂度 | 代码可运行但比应有的更难阅读或维护 |
|
||
| [security-and-hardening](skills/security-and-hardening/SKILL.md) | OWASP Top 10防护、认证模式、密钥管理、依赖审计、三层边界系统 | 处理用户输入、认证、数据存储或外部集成 |
|
||
| [performance-optimization](skills/performance-optimization/SKILL.md) | 先度量的方法——Core Web Vitals目标、性能分析工作流、包分析、反模式检测 | 存在性能要求或怀疑有性能回退 |
|
||
|
||
### 发布 - 有信心地部署
|
||
|
||
| 技能 | 功能 | 适用场景 |
|
||
|------|------|----------|
|
||
| [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) | 高级Staff工程师 | 以"Staff工程师会批准吗？"为标准的五维代码审查 |
|
||
| [test-engineer](agents/test-engineer.md) | QA专家 | 测试策略、覆盖率分析和Prove-It模式 |
|
||
| [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) | Core Web Vitals目标、前后端检查清单、测量命令 |
|
||
| [accessibility-checklist.md](references/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](https://abseil.io/resources/swe-book)》和谷歌[工程实践指南](https://google.github.io/eng-practices/)中的概念。你会在API设计中找到Hyrum定律，在测试中找到Beyonce规则和测试金字塔，在代码审查中找到变更规模和审查速度规范，在简化中找到Chesterton围栏原则，在git工作流中找到主干开发，在CI/CD中找到左移原则和功能标志，以及一个专门将代码视为负债的废弃技能。这些不是抽象原则——它们直接嵌入到智能体遵循的逐步工作流中。
|
||
|
||
---
|
||
|
||
## 贡献指南
|
||
|
||
技能应当**具体**（可操作的步骤，而非模糊建议）、**可验证**（有明确退出标准和证明要求）、**经过实战检验**（基于真实工作流）且**精简**（只包含引导智能体所需的内容）。
|
||
|
||
格式规范参见 [docs/skill-anatomy.md](docs/skill-anatomy.md)，贡献指南参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
MIT——在你的项目、团队和工具中自由使用这些技能。 |