agent-skills 实战指南：让 AI 编码 Agent 遵守生产级工程规范

📅 2026年5月7日 · 📝 Sakura · ⏱ 阅读约 10 分钟

AI Agent Claude Code Cursor GitHub Copilot 最佳实践 Gemini CLI 开源

AI 编码 Agent 写代码越来越快了但质量呢

你让 Claude Code 写一个新 API 它唰唰唰就写完了但代码没有异常处理没有类型注解没有单元测试甚至没有考虑边界情况

这不是 Agent 不够聪明是你没告诉它怎么干活

Google Chrome 团队的 Addy Osmani 注意到了这个问题他开源了一个叫 agent-skills 的项目本质是一套生产级工程技能 打包成 AI Agent 能直接读懂的规范文件让 Agent 遵循资深工程师的工作流来写代码

项目一发布就冲上 GitHub Trending 引发大量讨论因为它的思路和市面上大多数 AI 编码工具都不一样——不给 Agent 喂更多上下文而是教它怎么思考

agent-skills 解决什么问题

当前 AI 编码 Agent 的主要痛点是什么

缺乏工程纪律 — Agent 倾向于直接写代码跳过设计文档、测试规划和代码审查
质量不稳定 — 同样的 prompt 有时候产出很好有时候全是坑
上下文无限制膨胀 — 把所有规则塞进 system prompt 最后 Agent 记不住重点
跨工具不可移植 — 你在 Claude Code 里写好的规则换到 Cursor 又要重写

agent-skills 的方案很直接把资深工程师做事的流程写成结构化的 Markdown 文件每个文件对应一个技能比如"写 spec 之前不要写代码""测试就是规范"之类 Agent 根据当前任务自动激活对应的技能

这和上周我们聊的 Simon Willison 的观点其实一脉相承——当 Agent 写代码的成本趋近于零真正在瓶颈就变成了知道该写什么代码 agent-skills 就是在补这个短板

核心设计：7 个命令对应 20 个技能

agent-skills 把软件开发周期分成 6 个阶段对应 7 个 slash 命令

DEFINE → PLAN → BUILD → TEST → REVIEW → SHIP
/spec /plan /build /test /review /ship
+ /code-simplify

命令	阶段	核心理念
`/spec`	定义需求	Spec before code — 先写规范再写代码
`/plan`	规划任务	拆成小粒度的原子任务
`/build`	增量构建	一次只做一个切片
`/test`	验证覆盖	Tests are proof — 测试即规范
`/review`	代码审查	合并前必须审查提升代码健康度
`/code-simplify`	简化重构	清晰胜过聪明
`/ship`	生产发布	越快越安全

每个命令会激活一组底层技能项目内置了 20 个技能文件 自动根据任务类型选择

20 个工程技能一览

技能	作用	适用场景
idea-refine	结构化发散/收敛思考把模糊想法变成具体提案	刚有个粗略概念需要梳理
spec-driven-development	写 PRD 覆盖目标、边界、代码风格、测试要求	新项目 / 重大变更
planning-and-task-breakdown	将 PRD 拆成可并行的独立任务	拿到 spec 后要落地
incremental-development	一次只改动文件的一小部分渐进式推进	写代码阶段
testing-pyramid-and-coverage	按测试金字塔排优先级覆盖率目标 90%+	写测试
test-driven-development	红-绿-重构循环	需要 TDD 的核心逻辑
api-and-interface-design	以客户端视角设计 API 先定义再实现	启新 API
code-review	深度审查：逻辑正确性、安全性、性能、可维护性	合并前
security-review-checklist	OWASP Top 10 自动安全检查	涉及安全敏感代码
debugging-and-root-cause-analysis	假设驱动调试排除法定位根因	排查 Bug
code-simplification	冗余检测 + 复杂度削减	重构
error-handling-patterns	结构化错误处理不吞异常	服务端 / 网络代码
logging-and-observability	有意义的日志 + 可观测性埋点	生产级服务
performance-optimization	Profile 驱动优化不搞猜测	性能敏感代码
documentation-standards	代码即文档 + 必要的外部文档	公共 API / 库
dependency-management	依赖选择、版本锁定、安全审计	引入新依赖
migration-and-refactoring-strategies	渐进迁移不搞大爆炸	老代码改造
frontend-ui-engineering	组件化、可访问性、响应式、加载性能	前端开发
database-and-data-modeling	schema 设计、索引策略、迁移脚本	数据库改表
error-escalation-and-human-handoff	有明确判断什么情况下应该请人类介入	Agent 决策边界

安装指南：5 种 IDE 一句话安装

agent-skills 的设计原则是技能就是 Markdown 所以它能适配任何支持 instruction 文件的 AI 编码工具

Claude Code（官方推荐）

最方便的安装方式通过插件市场一键安装

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

如果你没有配置 GitHub SSH 可以用 HTTPS

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

本地开发模式

git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

装好后在 Claude Code 里输入 /spec 它就会自动激活 spec-driven-development 技能引导你写完整的 PRD

Cursor

把 skills 目录下的 SKILL.md 文件复制到 .cursor/rules/ 或者直接引整个目录

cp -r agent-skills/skills/*/.cursor/rules/

详情见项目的 docs/cursor-setup.md

Gemini CLI

Gemini CLI 支持原生技能注册

gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

也可以本地安装

gemini skills install ./agent-skills/skills/

GitHub Copilot

将 agents/ 目录下的定义作为 Copilot 角色技能内容放到 .github/copilot-instructions.md

详情见项目的 docs/copilot-setup.md

Windsurf / OpenCode / Kiro 等

规则文件放到对应 IDE 的规则配置目录即可 OpenCode 通过 AGENTS.md 加载 Kiro 放到 .kiro/skills/

Codex 或其他通用 Agent — 技能是纯 Markdown 你可以把它作为 system prompt 的一部分或者通过 instruction 文件加载详情看 docs/getting-started.md

实战用法

场景一：从零开始一个新项目

你有一个想法但不知道从哪开始

输入 /spec Agent 会启动 idea-refine 技能先帮你收敛想法然后启动 spec-driven-development 输出一份完整的 PRD 包含目标客户、功能定义、技术选型、边界条件、测试策略

然后输入 /plan Agent 把 PRD 拆成可并行的任务列表每个任务都是独立可交付的增量

场景二：给现有功能加新 API

输入 /build Agent 会自动激活 api-and-interface-design 技能先定义接口签名和请求/响应格式再写实现然后调用 testing-pyramid-and-coverage 技能保证测试覆盖

场景三：合并前的代码审查

输入 /review Agent 会激活 code-review 和 security-review-checklist 两个技能逐行审查代码的逻辑正确性、安全漏洞、性能问题、可维护性并输出审查报告

为什么 agent-skills 和普通 rules 不一样

很多人问这不就是 Copilot instructions / Cursor rules 的另一种写法吗

区别很大

结构化 — 每个技能有明确的步骤、验证关卡、反合理化表格（anti-rationalization table）防止 Agent 偷懒跳过关键步骤
分层调用 — /spec 不是一个 prompt 而是一个 meta-skill 它会按需再激活子技能形成工作流而不是平铺一大堆规则
跨 IDE 可移植 — 同一套 Markdown 文件 Claude Code、Cursor、Gemini CLI、Copilot 都能用不存在锁定
社区共建 — 开源项目任何人都可以 PR 新增技能修改已有技能

注意事项与最佳实践

不要一次激活太多技能 — Agent 的上下文窗口有限建议一次只激活 1-3 个相关技能
根据项目阶段选择技能 — 新项目用 spec + plan 已有项目改动用 build + review 排查 Bug 用 debugging
适当调整技能细节 — 官方技能偏向通用 web 开发如果你的项目有特殊规范可以 fork 修改
搭配 CI/CD 使用 — Agent 的 code review 只是辅助不要完全取代人类审查 + CI 自动化
结合 MCP 使用更强 — agent-skills 教 Agent 怎么做事 MCP 教 Agent 能做什么事两者互补

追求生产级 AI 代码质量？试试 agent-skills

👉 GitHub: addyosmani/agent-skills

克隆下来 5 分钟就能在你的 IDE 里跑起来

延伸阅读

如果你对 AI 编码 Agent 的正交思考感兴趣可以看看这几篇