agent-skills：面向 AI 编程代理的生产级工程技能库

这是什么

addyosmani/agent-skills 是一个面向 AI 编程代理（AI Coding Agents）的生产级工程技能包。该项目由知名前端工程师 Addy Osmani 维护，在 GitHub 上已获得近 50,000 星（★49544），是目前最热门的开源 AI 辅助开发工具之一。

其核心理念是将高级软件工程师在构建软件时使用的工作流（Workflows）、**质量门禁（Quality Gates）和最佳实践（Best Practices）**编码为结构化的技能。这些技能被打包成标准化的 Markdown 格式，旨在让 AI 代理在开发的每一个阶段都能一致地遵循这些工程纪律，从而缩小“原型质量”与“生产质量”之间的差距。

该项目不仅提供了一套技能定义，还包含了针对主流 AI 编程工具（如 Claude Code、Cursor、Gemini CLI 等）的集成指南、7 个斜杠命令（Slash Commands）以及预配置的专业领域代理人格（Personas）。

解决的问题

当前主流的 AI 编程代理（如 GitHub Copilot、Cursor 等）在默认行为上倾向于寻找“最短路径”。这种倾向往往导致以下问题：

1. 跳过关键工程步骤：AI 容易跳过需求规格说明（Specs）、单元测试、安全审查和代码重构，直接生成代码。
2. 缺乏工程纪律：AI 生成的代码可能缺乏可维护性、扩展性和安全性，无法直接用于生产环境。
3. 上下文缺失：通用提示词（Prompts）无法提供特定于 Google 等大厂级别的工程最佳实践，如 Hyrum's Law、Beyonce Rule 等具体原则的落地。
4. 验证不足：AI 往往缺乏自我验证机制，无法确保代码在构建、测试和运行时真正符合预期。

agent-skills 通过强制 AI 遵循结构化的工作流，解决了上述问题，确保 AI 生成的代码具备生产级的可靠性。

核心功能

1. 全生命周期技能覆盖

项目包含 23 个技能（22 个生命周期技能 + 1 个元技能 using-agent-skills），覆盖了软件开发的完整阶段：

• 定义阶段 (Define): interview-me, idea-refine, spec-driven-development
• 规划阶段 (Plan): planning-and-task-breakdown
• 构建阶段 (Build): incremental-implementation, context-engineering, source-driven-development, doubt-driven-development, frontend-ui-engineering, test-driven-development, api-and-interface-design
• 验证阶段 (Verify): browser-testing-with-devtools, debugging-and-error-recovery
• 审查阶段 (Review): code-review-and-quality, code-simplification, security-and-hardening, performance-optimization
• 发布阶段 (Ship): git-workflow-and-versioning, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, shipping-and-launch

2. 结构化技能解剖结构

每个技能（SKILL.md）都遵循严格的解剖结构，确保 AI 能够准确理解并执行：

• Frontmatter: 包含技能名称、描述和使用场景。
• Overview: 技能的功能概述。
• When to Use: 触发条件。
• Process: 分步工作流，包含检查点和退出标准。
• Rationalizations: 反合理化表。列出 AI 常见的借口（如“我稍后再加测试”）及其反驳理由，防止 AI 偷工减料。
• Red Flags: 错误信号检测。
• Verification: 不可协商的验证要求。要求提供测试通过、构建输出或运行时数据等证据，拒绝“看起来没问题”的主观判断。

3. 自动触发机制

• 斜杠命令: 提供 7 个斜杠命令，映射到开发生命周期，激活相应的技能组。
• 上下文自动激活: 根据用户当前行为自动触发技能。例如，设计 API 时自动激活 api-and-interface-design，构建 UI 时激活 frontend-ui-engineering。

4. 预配置的专业代理人格

提供 3 个预配置的专业领域代理人格（Specialist Personas），用于针对性的代码审查和深度分析。

5. 多工具集成支持

• Claude Code: 推荐工具，支持 Marketplace 安装或本地配置。
• Cursor: 支持将 SKILL.md 复制到 .cursor/rules/ 目录。
• Gemini CLI: 支持原生技能安装或添加到 GEMINI.md。
• Windsurf: 支持添加到规则配置。
• OpenCode: 通过 AGENTS.md 和技能工具执行。
• GitHub Copilot: 使用 agents/ 目录作为 Copilot 人格，技能内容放入 .github/copilot-instructions.md。
• Kiro IDE & CLI: 支持项目级或全局级技能存储。

亮点 / 与同类相比

1. 融入 Google 工程文化

与通用的提示词库不同，agent-skills 深度融入了 Google 的工程实践，包括：

• API 设计: 嵌入 Hyrum's Law（任何对实现细节的依赖都可能导致外部消费者失效）。
• 测试策略: 应用 Beyonce Rule（最好只做一次）和测试金字塔。
• 代码审查: 采用变更大小限制和审查速度规范。
• 简化: 应用 Chesterton's Fence（在理解现有规则的原因前，不要移除它）。
• Git 工作流: 采用主干开发（Trunk-based development）。
• CI/CD: 应用 Shift Left 原则和功能标志（Feature Flags）。
• 废弃管理: 将代码视为负债，提供专门的废弃技能。

2. “反合理化”机制

这是该项目最独特的亮点之一。每个技能都包含一个“反合理化表”，专门针对 AI 代理常见的偷懒行为（如跳过测试、忽略安全、过度复杂化）提供文档化的反驳理由。这迫使 AI 代理必须遵循工程纪律，而不是寻找捷径。

3. 验证驱动而非文本驱动

传统提示词往往依赖自然语言描述，而 agent-skills 强调验证（Verification）。每个技能都以明确的证据要求结束，如“测试必须通过”、“构建必须成功”、“运行时数据必须匹配”。这种“证据要求”机制确保了 AI 输出的质量是可衡量的。

4. 渐进式披露（Progressive Disclosure）

为了优化 Token 使用，技能包采用渐进式披露设计。SKILL.md 作为入口点，仅在需要时才加载支持性参考文档，保持上下文精简，提高 AI 处理效率。

5. 生产级工作流而非通用建议

与许多仅提供“最佳实践建议”的项目不同，agent-skills 提供的是具体的、可操作的步骤。它不是告诉 AI “要写测试”，而是提供一套完整的测试驱动开发（TDD）工作流，包括何时写测试、如何设计测试用例、如何验证测试覆盖率等。

适合谁用 / 上手

适合人群

• 使用 AI 编程代理的开发者: 特别是使用 Claude Code、Cursor、Gemini CLI 等工具，希望提升 AI 生成代码质量和工程规范性的开发者。
• 团队技术负责人: 希望将团队内部的工程最佳实践（如 Google 级别的规范）标准化并强制应用到 AI 辅助开发流程中的团队。
• 追求生产级代码质量的工程师: 对 AI 生成的“原型代码”不满意，希望获得可直接部署、经过充分测试和审查的代码的开发者。

上手指南

1. 安装与配置

根据你使用的 AI 工具选择相应的安装方式：

• Claude Code (推荐):

  # 通过 Marketplace 安装
  /plugin marketplace add addyosmani/agent-skills
  /plugin install agent-skills@addy-agent-skills
  
  #