Agent Skills保姆级教程:让AI像资深工程师写代码

GitHub Trending daily 第 2 名的 addyosmani/agent-skills，一句话说清楚：它不是新模型，也不是代码生成器，而是一套给 AI coding agent 用的“工程流程包”。

你平时让 AI 写代码，最怕什么？

不是它不会写。恰恰相反，它写得太快了。需求没问清，测试没补，安全边界没看，PR 一大坨，最后自信地告诉你“完成了”。说实话，这就是很多 AI 编程翻车的起点。

Agent Skills 想解决的正是这个问题：把资深工程师会做、但 AI 容易跳过的环节，拆成可复用的 Markdown 工作流，让代理在合适的时机加载、执行、验证。

我把仓库 README、docs、release notes、最近提交、作者博客和项目文件都看了一遍。先把论文问题说清楚：这个仓库没有配套论文或技术报告。公开检索里确实有几篇关于“Agent Skills”这个方向的 arXiv 论文，比如综述类论文和安全注入风险论文，但它们不是 addyosmani/agent-skills 的项目论文。所以下面按“项目笔记 + 保姆级教程”来拆，不编论文引用。

这个项目到底是什么

AI智能体学习网站：ai-agent-phd.com

Agent Skills 的核心单位是一个 SKILL.md 文件。

它通常长这样：

---
name:test-driven-development
description:Drives development with tests. Use when implementing any logic...
---

下面不是百科式知识点，而是流程：什么时候用、先做哪一步、常见偷懒借口是什么、怎么验证才算做完。

这个设计很关键。

很多团队会给 AI 写一大堆“请写高质量代码”“请注意安全”“请补测试”。问题是，这些话太像墙上的标语，AI 看过就算看过。Agent Skills 换了一种写法：不要只告诉 AI “要重视测试”，而是要求它按 Red、Green、Refactor 的顺序走，并且留下测试输出作为证据。

一句话概括：它把工程原则写成了可执行流程。

仓库现状：不是小玩具，已经很完整

AI智能体学习网站：ai-agent-phd.com

截至我查看时，GitHub 页面显示这个仓库约 54.8k star、6k fork、229 次提交。当前最新版本是 0.6.2，发布时间是 2026 年 6 月 11 日。

仓库主干很清晰：

agent-skills/
├── skills/        24 个技能
├── agents/        4 个专家 persona
├── references/    测试、安全、性能、可访问性检查表
├── docs/          各工具安装指南
├── commands/      Antigravity CLI 命令
├── .claude/       Claude Code slash commands
├── .gemini/       Gemini CLI slash commands
└── scripts/       技能校验脚本

24 个技能覆盖了完整研发链路：

定义需求：interview-me、idea-refine、spec-driven-development

拆计划：planning-and-task-breakdown

写代码：incremental-implementation、test-driven-development、frontend-ui-engineering、api-and-interface-design

做验证：browser-testing-with-devtools、debugging-and-error-recovery

审质量：code-review-and-quality、code-simplification、security-and-hardening、performance-optimization

上线前：git-workflow-and-versioning、ci-cd-and-automation、observability-and-instrumentation、shipping-and-launch

还有一个最重要的路由技能：using-agent-skills。它负责判断当前任务该用哪个技能。

我本地跑了一下仓库自带校验：

nodescripts/validate-skills.js

结果是：

24 skills checked - 0 error(s), 0 warning(s) - PASSED

这点挺加分。它不是随手堆 Markdown，而是有格式约束、CI 校验和贡献规范。

保姆级安装：不同工具怎么用

如果你用 Claude Code，作者推荐走 marketplace：

/pluginmarketplaceaddaddyosmani/agent-skills
/plugininstallagent-skills@addy-agent-skills

如果遇到 SSH clone 问题，直接用 HTTPS：

/pluginmarketplaceaddhttps://github.com/addyosmani/agent-skills.git
/plugininstallagent-skills@addy-agent-skills

本地开发模式：

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

如果你用 Gemini CLI：

geminiskillsinstallhttps://github.com/addyosmani/agent-skills.git--pathskills

如果你用 Antigravity CLI：

agyplugininstallhttps://github.com/addyosmani/agent-skills.git
agypluginlist

如果你用 Cursor，不建议一次塞满 24 个技能。先建 rules 目录，只放最常用的 2 到 3 个：

mkdir-p.cursor/rules
cp/path/to/agent-skills/skills/test-driven-development/SKILL.md.cursor/rules/test-driven-development.md
cp/path/to/agent-skills/skills/code-review-and-quality/SKILL.md.cursor/rules/code-review-and-quality.md
cp/path/to/agent-skills/skills/incremental-implementation/SKILL.md.cursor/rules/incremental-implementation.md

如果你用 Codex、Aider、Windsurf 或其他能吃 Markdown 指令的工具，也可以直接复制对应 SKILL.md 到项目规则里。它的可移植性就在这里：技能本质上是 Markdown，不绑定某一家 IDE。

新手别全装，先用这 4 个

讲真，第一次用不要贪多。

我建议先用这 4 个：

1. using-agent-skills

这是路由器。它会把任务映射到不同阶段：定义、计划、构建、验证、审查、发布。

它还写了几个非常硬的底线：先说清假设；遇到矛盾要停下来问；该反驳时要反驳；优先无聊但可靠的方案；只碰被要求碰的范围。

这几条比很多复杂提示词都有用。

2. spec-driven-development

适合新功能、跨文件改动、需求模糊的任务。

它要求先写清楚目标、技术栈、命令、目录结构、代码风格、测试策略、边界和验收标准。不是为了写文档而写文档，而是防止 AI 带着错误假设一路狂奔。

你可以这样要求代理：

Follow spec-driven-development first.
Write SPEC.md with objective, commands, testing strategy, boundaries and success criteria.
Do not implement until the spec is approved.

3. test-driven-development

这是最该常驻的技能。

它的核心不是“写测试”，而是“先写会失败的测试”。修 bug 时也一样，先写一个复现 bug 的测试，再修到它通过。

这对 AI 特别重要，因为 AI 很容易边修边解释，解释得还挺像真的。测试是把它拉回现实的绳子。

4. code-review-and-quality

这个技能把代码审查拆成五个轴：正确性、可读性、架构、安全、性能。

它还给了 PR 大小建议：100 行左右最好，300 行还能接受，1000 行就该拆。这个判断非常实用，因为 AI 最常见的坏习惯就是一次改太多。

一个完整实战流程

假设你要让 AI 给项目加一个“登录失败 5 次后临时锁定账号”的功能，不要直接说“帮我实现”。

更稳的说法是：

Use agent-skills workflow.

1. Start with spec-driven-development and write SPEC.md.
2. Break the spec into small tasks with planning-and-task-breakdown.
3. Implement one task at a time with incremental-implementation.
4. For each behavior, use test-driven-development.
5. Before finishing, review with code-review-and-quality and security-and-hardening.
6. Show the verification commands and results.

这段提示的价值在于，它不再把“完成”定义成“代码写出来”，而是定义成：

需求被写清楚
任务被拆小
每个行为有测试
安全边界被看过
审查维度被跑过
有命令输出证明它确实通过

AI coding 真正的分水岭，不是会不会生成代码，而是会不会留下可审查的证据。

项目里最值得偷走的 5 个设计

第一个是“流程优先，不写散文”。很多团队文档写得很长，但没有可执行步骤。Agent Skills 每个技能都像 runbook，读完就知道下一步做什么。

第二个是“反偷懒表”。每个技能都会列出 AI 常见借口，比如“这个太简单不用测试”“我之后再补”“测试过了就能发”。旁边直接写反驳。这个设计很妙，因为 LLM 最会合理化自己的偷懒。

第三个是“验证不可跳过”。每个技能都有 Verification 区，不允许用“看起来没问题”收尾。测试、构建、截图、日志、review 结果，都可以是证据。

第四个是“渐进加载”。不要把所有规则都塞进上下文。只在当前任务需要时加载对应技能。这能减少上下文污染，也更符合真实工程协作。

第五个是“范围纪律”。AI 很喜欢顺手重构，顺手删代码，顺手改风格。Agent Skills 明确要求只做当前任务相关的事。这个约束看着朴素，但能直接提高 PR 可合并率。

安全提醒：别把第三方技能当成无害文本

这里要泼一点冷水。

Skill 是 Markdown，但它会进入代理上下文。长文档、引用文件、脚本，都可能成为提示注入或供应链风险的入口。公开研究已经讨论过技能文件里隐藏恶意指令、脚本诱导权限扩大等问题。

所以实践上要记住几条：

只从可信仓库安装，团队最好 fork 后固定版本。
装之前读 SKILL.md，尤其是会调用脚本、网络、文件系统的技能。
不要给陌生技能配无限制权限。
涉及 rm、force push、数据库删除、密钥读取的流程必须有人确认。
把技能当代码审，不要当普通文档看。

Agent Skills 这个仓库本身的安全技能写得挺认真，但这不代表“所有技能生态都安全”。越是好用的抽象，越需要边界。

最终 verdict：值得用，但别神化

我的结论很明确：如果你已经在严肃使用 AI coding agent，这个仓库值得加入工具箱。

它最适合三类人：

个人开发者：想让 AI 少跳测试、少乱改范围。
小团队：想把工程习惯沉淀成可复用流程。
平台/工具团队：想研究技能、persona、slash command 怎么组合成一个代理工作流。

但它不是魔法。

它不能保证模型永远服从，也不能替你跑 CI，更不能替代人类 review。最好的用法是把它和仓库里的 AGENTS.md、CI、测试脚本、代码审查、权限控制放在一起，形成真正的工程闭环。

我的实操建议：

先固定到最新稳定 tag，比如 0.6.2。个人用户用 Claude Code marketplace 最省事；团队用户建议 fork 一份，删掉不用的技能，只保留 4 到 8 个关键流程。第一批别超过这些：using-agent-skills、spec-driven-development、planning-and-task-breakdown、incremental-implementation、test-driven-development、code-review-and-quality、security-and-hardening。

再把你的项目特有规则写进 AGENTS.md：包管理器、测试命令、不能碰的目录、上线边界、数据库变更审批。Agent Skills 负责通用工程纪律，你自己的规则负责项目上下文。

最重要的一点：每次让 AI 做完事，都问它要证据。

不是“你完成了吗”，而是：

Show the spec, changed files, tests added, commands run, and review findings.

这才是 Agent Skills 真正想教你的东西：让 AI 写代码不难，难的是让它按可验证、可审查、可上线的方式写代码。