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

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

📋 目录

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

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 参数：

# 只安装代码审查技能
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

# 从仓库安装
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

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

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

Command Code

Command Code 内置了 cmd skills 命令：

# 项目级安装（当前目录）
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 审计

使用建议

从 /spec 开始：对于新项目或重大变更，始终先用 /spec 定义规范。
信任流程：让 AI 严格遵循技能工作流，尤其是在测试和代码审查阶段。
利用 interview-me：需求模糊时，使用此技能让 AI 通过提问理清需求。
定期运行 /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。