Agent Skills 生产级工程技能包详细部署教程

Agent Skills 是一套为 AI 编程助手准备的生产级工程技能包，它将资深工程师的软件工程最佳实践（如规范驱动开发、测试驱动开发、代码审查等）编码为结构化工作流，让 AI 助手能像资深工程师一样思考和行动。本教程将指导您在不同 AI 工具中安装和使用这套技能。

📋 目录

  1. Agent Skills 是什么
  2. 核心技能概览
  3. 快速开始：通用安装方法
  4. 特定工具安装指南
  5. 核心工作流：技能与命令
  6. 配置与最佳实践
  7. 更新与卸载
  8. 常见问题排查

Agent Skills 是什么

Agent Skills 是一套将工程实践编码为 AI 助手可执行工作流的技能包。它的核心理念是：AI 助手默认走最短路径，通常会跳过规范、测试、安全审查等关键步骤，而 Agent Skills 为其提供了结构化的、必须遵循的工作流。

设计哲学：

  • 流程而非散文：每个技能是分步骤的工作流，而非参考资料。
  • 反合理化：每个技能都包含一张“借口与反驳”表，防止 AI 跳过必要步骤。
  • 可验证性：每个技能都有明确的退出标准和证据要求（如测试通过、构建成功）。
  • 渐进式披露：SKILL.md 是入口，详细参考资料仅在需要时加载，节省 Token。

核心技能概览

此技能包包含 25 个技能（24 个生命周期技能 + 1 个元技能），覆盖软件开发的完整生命周期：

阶段 技能名称 功能描述
元 using-agent-skills 映射工作到正确的技能工作流，定义共享操作规则
定义 interview-me 通过一问一答的方式挖掘用户真实需求
idea-refine 通过发散/收敛思维将模糊想法转化为具体提案
spec-driven-development 编写包含目标、结构、风格、测试和边界的 PRD
constraint-driven-development 通过访谈设定质量门禁，生成 CONSTRAINTS.md
计划 planning-and-task-breakdown 将规范分解为可验证的小任务，明确依赖关系
构建 incremental-implementation 薄垂直切片实现，每个切片均测试、验证、提交
test-driven-development 红-绿-重构循环，严格执行测试金字塔
context-engineering 为 AI 提供正确的上下文信息（规则文件、MCP 集成）
source-driven-development 所有框架决策基于官方文档，可溯源
doubt-driven-development 对高风险决策进行对抗性审查，支持跨模型升级
frontend-ui-engineering 组件架构、设计系统、响应式设计、WCAG 2.1 AA 无障碍
api-and-interface-design 契约优先设计，处理 Hyrum’s Law 和版本控制
验证 browser-testing-with-devtools 使用 Chrome DevTools MCP 进行运行时检查
debugging-and-error-recovery 五步法：复现、定位、简化、修复、防护
审查 code-review-and-quality 五轴审查，变更大小控制（~100 行），问题分级
code-simplification 在保持行为不变的前提下降低复杂度
security-and-hardening OWASP Top 10 预防，认证模式，密钥管理
performance-optimization 基于测量的优化，Core Web Vitals 目标
交付 git-workflow-and-versioning 主干开发，原子提交，变更大小控制
ci-cd-and-automation Shift Left 原则，特性标志，质量门禁流水线
deprecation-and-migration 代码即负债理念，强制/建议弃用模式
documentation-and-adrs 架构决策记录，API 文档，记录“为什么”
observability-and-instrumentation 结构化日志，RED 指标，OpenTelemetry 追踪
shipping-and-launch 预发布清单，特性标志生命周期，分阶段发布

快速开始：通用安装方法

这是最快、兼容性最广的安装方式，使用 npx skills add 命令，支持 70+ 种 AI 工具（Claude Code, Cursor, Codex, Copilot, Cline 等）。

1. 安装所有技能（推荐）

在终端中执行：

1
npx skills add addyosmani/agent-skills

此命令会将所有 25 个技能安装到当前工作目录下的 .factory/skills/ 或对应工具的特定目录。

2. 安装特定技能

如果只想安装某个技能，可以使用 --skill 参数：

1
2
3
4
5
# 只安装代码审查技能
npx skills add addyosmani/agent-skills --skill code-review-and-quality

# 只安装需求访谈技能
npx skills add addyosmani/agent-skills --skill interview-me

注意：单个技能安装时，引用的共享检查清单（位于 references/ 目录）不会被自动复制，如果需要这些资料，建议克隆整个仓库或手动复制。

3. 浏览所有技能

在安装前，可以先查看所有可用技能的列表：

1
npx skills add addyosmani/agent-skills --list

特定工具安装指南

除了通用方法，Agent Skills 也为主流 AI 工具提供了原生集成方式。

Claude Code（推荐）

方法一：通过插件市场安装（推荐）
在 Claude Code 会话中依次执行：

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

解决 SSH 权限问题：如果遇到 Permission denied (publickey) 错误，可以：

  • 方法 A：使用 HTTPS URL 添加市场：

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

  • 方法 B：配置 Git 全局重写规则（推荐，一劳永逸）：

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

方法二：本地开发模式

1
2
3
git clone https://github.com/addyosmani/agent-skills.git
cd agent-skills
claude --plugin-dir .

Codex

Codex 在 v0.122+ 版本支持原生插件：

1
2
codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills

安装后，可在对话中使用 @ 调用技能，例如 @spec-driven-development。

Cursor

将技能同步到 .cursor/skills/ 目录，将简短策略放在 .cursor/rules/*.mdc 中（不要将完整技能内容粘贴到规则文件）。详细步骤请参考 docs/cursor-setup.md。

Gemini CLI

1
2
3
4
5
6
# 从仓库安装
gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

# 从本地克隆安装
git clone https://github.com/addyosmani/agent-skills.git
gemini skills install ./agent-skills/skills/

Antigravity CLI

1
2
3
4
5
# 从仓库安装
agy plugin install https://github.com/addyosmani/agent-skills.git

# 从本地克隆安装
agy plugin install ./agent-skills

Command Code

Command Code 内置了 cmd skills 命令：

1
2
3
4
5
6
7
8
# 项目级安装（当前目录）
cmd skills add addyosmani/agent-skills

# 全局安装（所有项目）
cmd skills add addyosmani/agent-skills --global

# 安装特定技能
cmd skills add addyosmani/agent-skills -s spec-driven-development

安装后，技能会出现在 TUI 的斜杠菜单中，例如 /spec-driven-development。

其他工具（Windsurf, OpenCode, GitHub Copilot, Kiro）

Agent Skills 是纯 Markdown 格式，兼容任何接受系统提示或指令文件的 AI 代理。请参考 docs/ 目录下对应工具的详细设置指南。

核心工作流：技能与命令

Agent Skills 提供了 9 个斜杠命令，映射到软件开发的生命周期，每个命令会自动激活所需的技能组合。

你做的事 命令 核心原则
定义要构建什么 /spec 先写规范，再写代码
计划如何构建 /plan 分解为小而原子的任务
增量构建 /build 一次构建一个切片
证明它工作 /test 测试就是证明
设定质量门槛 /constraints 一次性设定，处处执行
合并前审查 /review 改善代码健康
审查 Web 性能 /webperf 优化前先测量
简化代码 /code-simplify 清晰胜于聪明
交付到生产 /ship 越快越安全

高级用法：/build auto 命令在规范存在时，会生成计划并自动执行每个任务（每个任务仍会进行 TDD 并单独提交），在失败或高风险步骤时会暂停。

技能自动激活：部分技能会根据您的操作自动激活，例如：

  • 设计 API → 自动触发 api-and-interface-design
  • 构建 UI → 自动触发 frontend-ui-engineering

配置与最佳实践

核心参考检查清单

技能包包含 7 个核心参考清单，存储在 references/ 目录下，技能会按需加载：

参考文件 覆盖内容
definition-of-done.md 项目级完成标准 vs. 任务级验收标准
testing-patterns.md 测试结构、命名、模拟、React/API/E2E 示例
security-checklist.md 提交前检查、认证、输入验证、CORS、OWASP Top 10
performance-checklist.md Core Web Vitals 目标、前后端检查清单
accessibility-checklist.md 键盘导航、屏幕阅读器、ARIA、测试工具
observability-checklist.md 结构化日志、RED/USE 指标、追踪、告警
orchestration-patterns.md 多角色编排模式与反模式

专业智能体角色

技能包包含 4 个预配置的专业角色（在 agents/ 目录）：

角色 视角
code-reviewer 资深架构师，五轴代码审查
test-engineer QA 专家，测试策略和覆盖率分析
security-auditor 安全工程师，漏洞检测和 OWASP 评估
web-performance-auditor Web 性能工程师，Core Web Vitals 审计

使用建议

  1. 从 /spec 开始：对于新项目或重大变更，始终先用 /spec 定义规范。
  2. 信任流程：让 AI 严格遵循技能工作流，尤其是在测试和代码审查阶段。
  3. 利用 interview-me：需求模糊时，使用此技能让 AI 通过提问理清需求。
  4. 定期运行 /review：合并代码前，用此技能进行标准化代码审查。

更新与卸载

更新技能

  • 通过 npx skills 安装的：重新运行安装命令即可更新到最新版本。
  • 通过 Claude Code 市场安装的：在 Claude Code 中使用 /plugin update agent-skills@addy-agent-skills（部分版本支持）。
  • 通过其他原生方式安装的：请参考对应工具的插件更新命令，或重新执行安装步骤。

卸载技能

  • 通用 npx skills 安装：手动删除对应技能目录。项目级安装在 .factory/skills/，全局安装通常在 ~/.factory/skills/ 或对应工具的特定目录。
  • Claude Code 市场：使用 /plugin uninstall agent-skills@addy-agent-skills。
  • 其他工具：删除技能目录或使用对应工具的插件移除命令。

常见问题排查

问题：npx skills add 命令找不到。

  • 解决：确保 Node.js 和 npm 已安装（版本 16+）。skills 是一个独立的 npm 包，npx 会自动下载执行。

问题：Claude Code 插件安装提示 SSH 权限被拒。

  • 解决：按照前文“Claude Code”部分的方法，使用 HTTPS URL 或配置 Git 全局重写规则。

问题：安装单个技能后，运行时提示找不到 references/ 目录。

  • 解决：npx skills add --skill 仅复制技能目录，不复制仓库级别的 references/。解决方法：
    1. 使用 npx skills add（不带 --skill）安装全部技能。
    2. 克隆整个仓库：git clone https://github.com/addyosmani/agent-skills.git。
    3. 手动将所需的 references/*.md 文件复制到技能目录下的 references/ 子目录中。

问题：技能未自动激活或命令未生效。

  • 解决：确认你的 AI 工具版本支持技能/插件功能。检查技能是否被正确放置在工具的技能目录下（如 Claude Code 的 ~/.claude/skills/）。尝试重启 AI 工具会话。

通过以上步骤，您应该能顺利为您的 AI 编程助手装备上这套生产级的工程技能包。从下一个任务开始，尝试使用 /spec 或 /plan 命令，体验结构化工作流带来的质量和效率提升。如有更多问题，可查阅项目 docs/ 目录下的详细文档或提交 GitHub Issue。