代理技能：AI编码最佳实践

项目概述

Agent Skills 是一个生产级库，包含 20 个可重用的基于 Markdown 的工作流指令，这些指令将资深工程师的最佳实践编码到 AI 编码代理中，防止它们在整个软件开发生命周期中偷工减料。

项目背景与定位

为什么存在

AI 编码代理能力很强，但缺乏纪律性。如果不加以约束，它们会跳过规范、省略测试、忽略安全审查，并用听起来合理的借口来合理化捷径。Agent Skills 由 Addy Osmani 创建——他是一位在谷歌工程文化中有深厚根基的开发者倡导者——旨在通过将有主见的、可验证的工作流直接嵌入代理的指令层来解决这个问题。该项目将代码视为一种负债，而非资产，并坚持认为“看起来正确”永远不能替代可衡量的证据。

与类似项目的区别

大多数提示库是临时收集的技巧。Agent Skills 在三个方面有所不同：

生命周期覆盖 — Skills 涵盖每个阶段：定义 → 计划 → 构建 → 验证 → 审查 → 发布，而不是只针对一个阶段。
反合理化护栏 — 每个 Skill 都明确指出了代理常走的捷径，并提供了有据可查的反驳，使得拒绝比遵守更困难。
工具无关的可移植性 — 由于每个 Skill 都是纯 Markdown，因此它可以直接在 Claude Code、Cursor、Windsurf、Gemini CLI、GitHub Copilot、Kiro IDE 或任何接受系统提示的代理中使用，无需修改。

功能类别

📋 定义 — 规范 Skills · 3 个 Skills
代表性示例：系统需求、API 合约、数据模型设计。
目的：强制代理在编写第一行代码之前确定需求。

🗺 计划 — 架构与分解 Skills · 4 个 Skills
代表性示例：任务分解、架构规划、依赖映射、时间线估算。
目的：确保代理生成可审计的计划，而不是直接进入实现。

🔨 构建 — 实现 Skills · 4 个 Skills
代表性示例：增量交付、模块化强制执行、代码组织、基于主干的分支。
目的：让代理以小而可验证的步骤进行构建，这些步骤始终可以合并。

✅ 验证 — 测试 Skills · 4 个 Skills
代表性示例：单元测试、集成测试、测试覆盖率门禁、测试模式参考清单。
目的：让代理通过测试来证明功能，而不是假设正确性。

🔍 审查 — 质量门 Skills · 3 个 Skills
代表性示例：代码审查、安全审计、性能审查、可访问性清单。
目的：在批准合并之前应用与资深工程师相同的标准。

🚀 发布 — 部署 Skills · 2 个 Skills
代表性示例：生产就绪清单、部署策略、回滚计划。
目的：确保代理在将更改推送到生产环境之前考虑可观察性、回滚和值班影响。

核心亮点

20 个贯穿生命周期的 Skills 集中在一起 — 从第一个规范到生产部署，每个阶段至少有一个专用的 Skill，包含分步程序和验证门禁。

七个映射到工作流阶段的斜杠命令 — /spec、/plan、/build、/test、/review、/code-simplify 和 /ship 为团队提供了用于指示代理的共享词汇，无论使用何种 IDE。

三个专业代理角色 — 代码审查员、测试工程师和安全审计员角色与 Skills 一起提供，让团队可以启动专注于特定质量工作的代理。

四个参考清单 — 用于测试模式、安全实践、性能优化和可访问性标准的独立、可链接的清单，充当轻量级的合规门禁。

工程原理锚定 — Skills 嵌入了命名的原理（Hyrum 定律、Beyonce 规则、Chesterton 围栏），以便代理能够理解实践存在的原因，而不仅仅是机械地遵循它。

一流的多工具集成 — 专用的配置目录（.claude/、.cursor/、.windsurf/、.gemini/、.opencode/）和每个平台的设置指南意味着在任何 IDE 中采用零摩擦。

按角色划分的使用案例

通用开发者
使用七个斜杠命令作为日常工作流驱动程序。在开始任何功能之前运行 /spec，在实现过程中运行 /build，在打开 PR 之前运行 /review。这些 Skills 充当了资深工程师在您身后监督，而无需安排会议的开销。

DevOps / 平台工程师
专注于发布 Skills 和生产就绪清单，以确保 AI 生成的部署代码在任何更改到达生产环境之前都考虑了回滚策略、功能标志和可观察性钩子。

数据与研究工程师
在代理开始生成管道或转换代码之前，使用定义和计划 Skills 来强制执行清晰的数据合约和模式文档。测试 Skills 有助于强制执行数据质量断言的覆盖率。

产品团队
使用规范 Skill 作为需求翻译层：将产品简报输入运行规范 Skill 的代理，以获得结构化的、面向开发者的需求文档，从而减少与工程部门的来回沟通。

快速入门

🔍 如何查找资源

浏览存储库中的 skills/ 目录以获取所有 20 个 .md Skill 文件，agents/ 目录以获取三个专业角色，references/ 目录以获取四个独立清单。docs/ 目录包含每个工具的设置指南。

skills/          # 20 个生命周期 Skills
agents/          # code-reviewer, test-engineer, security-auditor
references/      # testing, security, performance, accessibility
docs/            # per IDE/tool setup guides

🛠 如何安装 / 集成

选项 1 — Claude Code 插件市场（推荐）

/plugin marketplace add addyosmani/agent-skills

选项 2 — 为任何工具本地克隆

git clone https://github.com/addyosmani/agent-skills.git
cd agent-skills

# Claude Code — 指向本地插件目录
claude --plugin-dir ./

# Gemini CLI
gemini skills install https://github.com/addyosmani/agent-skills.git

选项 3 — 将单个 Skills 复制为系统提示

# 在任何代理中使用任何 Skill 作为系统提示
cat skills/review.md   # 粘贴到您的工具的系统提示中

Cursor / Windsurf / Kiro IDE — .cursor/、.windsurf/ 和 .opencode/ 目录包含即用型配置文件。请遵循 docs/ 中的每个工具指南。

🤝 如何贡献

git clone https://github.com/addyosmani/agent-skills.git
cd agent-skills

# 按照现有约定创建新 Skill
cp skills/review.md skills/my-skill.md
# 编辑 my-skill.md — 包括：目标、步骤、验证门禁、反合理化

# 提交拉取请求
git checkout -b feat/my-skill
git add skills/my-skill.md
git commit -m "feat: add my-skill for <purpose>"
git push origin feat/my-skill
# 在 https://github.com/addyosmani/agent-skills/pulls 打开 PR

项目结构

agent-skills/
├── skills/                  # 20 个生命周期 Skill Markdown 文件
│   ├── spec.md              # 定义需求
│   ├── plan.md              # 将工作分解为任务
│   ├── build.md             # 增量实现
│   ├── test.md              # 验证工作流
│   ├── review.md            # 合并前的质量门
│   ├── code-simplify.md     # 复杂性降低
│   └── ship.md              # 生产部署就绪性
├── agents/                  # 专业代理角色
│   ├── code-reviewer.md
│   ├── test-engineer.md
│   └── security-auditor.md
├── references/              # 独立质量清单
│   ├── testing-patterns.md
│   ├── security.md
│   ├── performance.md
│   └── accessibility.md
├── .claude/commands/        # Claude Code 斜杠命令集成
├── .gemini/commands/        # Gemini CLI 集成
├── .cursor/                 # Cursor IDE 配置
├── .windsurf/               # Windsurf IDE 配置
├── .opencode/               # Kiro / OpenCode IDE 配置
├── docs/                    # 每个工具的设置指南
└── README.md                # 项目概述和快速入门

许可证

MIT 许可证


✅ 允许	在个人、开源和商业项目中使用
✅ 允许	分叉、修改和重新分发（需注明出处）
✅ 允许	将 Skills 打包到专有 AI 产品或 SaaS 工具中
❌ 禁止	在重新分发的副本中删除版权声明
ℹ️ 注意	不提供任何保修；贡献者不对生产使用结果负责

常见问题解答

问：我是否需要专门使用 Claude Code，还是任何 AI 编码工具都可以？
答：任何接受 Markdown 作为系统提示的工具都可以。所有 20 个 Skills 都是纯 .md 文件。Claude Code 是具有最丰富用户体验（斜杠命令、插件市场）的主要集成，但 Cursor、Windsurf、Gemini CLI、GitHub Copilot 和任何通用代理同样适用。

问：一个“Skill”与简单地粘贴一个提示有什么区别？
答：每个 Skill 都是一个结构化的工作流，而不是一次性的指令。它包括一个明确的目标、带有每个阶段验证门禁的编号步骤，以及一个“反合理化”部分，该部分预测并反驳代理常走的捷径。这使得 Skill 比简单的提示更强大。

问：我能否将我团队的内部约定添加到 Skill 中？
答：是的——而且这是鼓励的工作流程。分叉仓库，编辑相关的 .md 文件以包含您团队的具体标准（例如，内部测试框架、部署清单），并将您的代理指向您的分叉。选择 Markdown 格式是为了方便自定义。

问：这会显著减慢 AI 编码代理的速度吗？
答：Skills 会增加步骤，但它们可以防止因无纪律的生成而导致的成本高昂的返工。该项目将其视为一种有意识的权衡：初始输出速度较慢，但到达审查或生产阶段的缺陷要少得多。

问：三个专业角色与 20 个 Skills 有何不同？
答：Skills 是工作流指令——它们告诉代理如何执行任务。角色（agents/）配置代理的身份和优先级以进行专注工作（例如，始终像安全审计员一样思考）。它们是互补的：您可以使用安全审计员角色应用安全审计 Skill，以获得最彻底的结果。

快速链接

资源	URL
GitHub 仓库	https://github.com/addyosmani/agent-skills
插件市场 (Claude Code)	`/plugin marketplace add addyosmani/agent-skills`
问题与讨论	https://github.com/addyosmani/agent-skills/issues
发布	https://github.com/addyosmani/agent-skills/releases
作者	https://github.com/addyosmani

摘要

Agent Skills 是一个罕见的开源项目，它解决了结构性问题而非功能差距：它使 AI 编码代理的行为像有纪律的资深工程师，而不是过于自信的初级工程师。凭借超过 25k 的 GitHub 星标、对每个主要 AI 编码平台的头等支持以及 MIT 许可证，任何已经在开发工作流中使用 AI 的团队都可以立即使用它。希望从其 AI 编码工具中获得一致、可审计、生产就绪的输出的开发者，应考虑将 Agent Skills 作为其代理配置的第一层。

agent-skills