1. 为什么 Agent 有了大模型还不够还需要 Skills如果你最近在用 Claude Code、Cursor 这类 AI 编程工具大概率遇到过一种情况模型很强但总觉得“使唤不动”。让它改一个文件它改得很漂亮让它连续完成“先分析项目结构、再定位问题、再给出修复方案、最后补充测试”这种多步骤任务时它就开始跑偏不是漏步骤就是自己发挥一套做法。问题出在哪不是模型能力不够而是你没有给 Agent 一套足够明确的“操作手册”。传统的方式是把所有要求塞进 system prompt或者每次对话开头写一大段提示词。这在简单任务上有效但一旦任务变复杂提示词越长模型越容易抓不住重点。而且 prompt 是全局的Agent 做代码审查时带上一堆“生成提交信息”的规则做重构时又带上一堆“安全审计”的要求互相干扰。Agent Skills 要解决的就是这个问题把某一类任务的知识、步骤、规则和输出格式封装成一个独立、可复用、按需加载的“技能包”。Agent 遇到对应场景时才加载它用完即走互不干扰。我关注到这个方向是因为 Google Chrome 团队的前端工程师 Addy Osmani 在 GitHub 上建了一个agent-skills仓库专门收集面向 AI 编程 Agent 的实用 Skills。这个仓库的价值不在于代码量而在于它把过去只存在于资深开发者脑子里的工作流变成了 Agent 可以直接执行的结构化资产。这篇文章会讲清楚三件事Agent Skills 到底是什么、一个 Skill 文件内部长什么样、以及你自己怎么写出可复用的 Skill。读完你可以直接照抄思路给手头的 AI 编程工具配上一套自己的技能库。2. Agent Skills 的核心概念与适用场景2.1 什么是 Agent Skill先给一个直观定义Agent Skill 是一组预先编写好的指令和资源用来教会 Agent 如何完成某一类特定任务。它不是一个插件也不是一个独立的程序。它更像是一本“岗位说明书”——你告诉 Agent当你要做代码审查时先看哪些文件、按什么顺序分析、重点关注什么风险、最终用什么格式输出。从技术实现上看一个 Skill 通常是一个目录里面包含一个带 YAML frontmatter 的 Markdown 文件必要时再加上脚本、模板和参考文档。当前比较流行的实现来自 Anthropic 提出的 Claude Skills 规范Addy Osmani 的agent-skills仓库也是沿着这个思路整理“可复用的技能定义”。skills/ ├── code-review/ │ ├── SKILL.md │ └── checklists/ │ └── security-checklist.md ├── commit-message/ │ └── SKILL.md前端开发者可以把 Skill 想象成一个设计模式它不直接给你代码但告诉你“遇到这种问题按这个套路做最稳妥”。2.2 Skill 与 Prompt、Plugin、MCP 的区别很多读者会把 Skill 和另外几个概念混在一起这里做个区分。概念本质触发方式典型场景Prompt一次性指令每次对话手动输入让模型解释代码、写一段脚本Plugin扩展能力的独立软件用户或系统显式调用让 Agent 操作浏览器、执行外部 APIMCP统一协议连接外部工具和数据源按需调用让 Agent 读数据库、查文件系统Skill任务流程和知识的封装按任务类型自动匹配代码审查、重构、生成提交信息、写测试打个比方MCP 解决的是“Agent 的手能伸到哪里”Skill 解决的是“Agent 脑子里该用什么流程办事”。前者是权限和能力边界后者是方法论和工作流。2.3 适用场景什么任务适合做成 Skill不是所有任务都需要 Skill。判断标准很简单这任务是不是频繁发生、是不是有固定步骤、是不是容易做错。适合做成 Skill 的典型场景代码审查审查步骤固定不同项目的审查重点不同但流程可以沉淀。提交信息生成要遵循 Conventional Commits 规范模板固定。技术方案评审需要按一定维度评估方案的可行性、风险、成本。新旧代码迁移迁移过程有固定步骤容易遗漏边界情况。性能优化先定位瓶颈、再分析原因、再给出方案每一步都有约定。不适合做成 Skill 的场景是一次性任务、没有固定流程的开放性问题、依赖实时数据且每次变化很大的判断。2.4 传统方式与 Skill 方式的差异传统方式下你每次都要在对话里输入请帮我审查这个项目的代码重点看安全问题 然后检查性能问题最后检查可读性 输出格式要包含问题严重程度、文件位置、修改建议……这种方式有两个问题第一每次输入都很长效率低第二表述每次都有细微差异Agent 执行标准不稳定。Skill 方式下你只需要说“审查当前分支的代码”Agent 自动加载code-reviewSkill按内部的检查清单逐项执行。人和 Agent 的沟通成本降低了Agent 输出的一致性提高了。3. Addy Osmani 是谁agent-skills 仓库定位是什么3.1 项目背景Addy Osmani 是 Google Chrome 团队成员长期从事 Web 性能和前端工程化相关工作写过《Learning JavaScript Design Patterns》等书籍也在持续分享前端架构和工程效率方面的经验。近两年他明显把关注重心转向了“如何用 AI 改善开发工作流”agent-skills仓库正是这个方向的实践产物。从仓库定位看它不是一个大而全的框架更像是一个精心挑选的“技能集合”。里面收集的 Skill 大多围绕前端与 Web 开发场景展开比如代码审查、性能分析、依赖审查、提交信息规范等。每个 Skill 都力求精炼让 Agent 拿到就能用减少多余的说明和噪音。3.2 这个仓库的价值在哪这个仓库最值得学习的地方不是某一个 Skill 写得有多惊艳而是选材和封装思路。先说选材。代码审查、依赖安全检查、提交信息生成这些都是前端工程里几乎每天都要做的事频次高、规则相对明确做成 Skill 的收益很高。反观一些仓库喜欢收集“让 Agent 写整站应用”这种大而全的 Skill结果执行起来很不可控。再说封装。一个 Skill 文件不是越长越好而是要把“什么是这个任务的关键约束”讲清楚。比如代码审查的 Skill它会强调先看 diff、按安全/性能/可读性分层、每个问题都要给出文件与行号和修改建议这些约束直接决定了 Agent 的输出质量。3.3 如果是新手怎么读这个仓库我的建议是不要一次性把仓库里的所有 Skill 都搬进你的配置里。正确做法是先挑一个你最痛的点比如“提交信息总是不规范”把这个 Skill 用起来跑一两周观察 Agent 的输出有没有变好稳定之后再叠加下一个 Skill。Skill 不是越多越好而是越贴合你的工作流越好。4. 环境准备与前置条件4.1 需要什么运行环境Skill 本身不需要安装任何依赖因为它本质上是文本文件和可选脚本。你需要准备的是一个支持 Agent Skills 机制的 AI 编程工具目前 Claude Code、Cursor 等工具对 Skill 的目录约定和支持程度不同建议优先选择明确支持SKILL.md约定的工具。一个存放 Skill 的目录项目中通常放在.claude/skills/下。Git 客户端方便管理和同步你的 Skill 文件。基础的 Markdown 和 YAML 语法知识不需要精通能看懂 frontmatter 配置即可。版本方面各家工具对 Skill 规范和加载机制仍在快速演进不建议绑定某个固定版本。本文演示的是通用思路具体加载方式以你使用的工具官方文档为准。4.2 理解 YAML frontmatterSkill 文件的主体是 Markdown文件头部有一段 YAML 格式的元信息用来描述这个 Skill 的名称、描述和适用场景。这段 frontmatter 非常关键因为它决定了 Agent 什么时候会主动加载这个 Skill。如果描述写得太泛Agent 会在不相关的任务里错误触发如果写得太窄Agent 又找不到它。下面是一个可复制的模板--- name: code-review description: 用于对代码变更进行系统化审查检查安全性、性能、可维护性并输出结构化审查报告。 ---name是 Skill 的唯一标识description是给 Agent 看的触发条件说明。写描述时尽量包含“触发词 任务 输出方式”三个要素。4.3 工具链准备步骤以常见项目结构为例环境准备只需要三步# 1. 在项目根目录创建 skills 目录 mkdir -p .claude/skills/code-review # 2. 创建 SKILL.md 文件 touch .claude/skills/code-review/SKILL.md # 3. 初始化 git 跟踪可选但推荐 git add .claude/skills/ git commit -m feat: add code-review skill如果你使用的是 Cursor需要注意它当前对 Skills 原生目录的支持不如 Claude Code 那么直接更常见的方式是通过.cursor/rules/或.mcp.json来间接达到类似效果。但这不影响你编写 Skill 文件本身因为文件格式是可以通用的差别只在于加载方式。5. 从零写一个可复用的 Skill完整示例5.1 Skill 的标准目录结构一个标准的 Skill 目录至少包含一个SKILL.md推荐按下面的结构组织.claude/skills/ └── code-review/ ├── SKILL.md ├── checklists/ │ ├── security.md │ └── performance.md └── scripts/ └── extract-diff.sh其中SKILL.mdSkill 的主文件包含任务说明、执行步骤、输出要求。checklists/可选的检查清单Agent 执行时会逐项核对。scripts/可选的辅助脚本比如提取 git diff、统计数据等。5.2 示例一代码审查 Skill下面是一个面向 Web 项目的代码审查 Skill 示例文件路径为.claude/skills/code-review/SKILL.md--- name: code-review description: 对当前分支的代码变更进行系统化审查重点检查安全性、性能、可访问性和可维护性输出按严重程度分级的结构化报告。当用户要求审查代码、检查 Pull Request 或 review diff 时使用。 --- # 代码审查技能 你是一位资深前端代码审查专家需要帮助开发者完成系统化的代码审查。 ## 执行步骤 1. 获取当前分支相对主分支的 diff bash git diff main...HEAD如果 diff 太大先按文件类型分组优先审查以下高风险文件涉及用户输入处理的文件涉及鉴权和权限判断的文件涉及数据库查询和外部 API 调用的文件新增依赖的配置文件按以下维度逐项分析安全性XSS、CSRF、注入、敏感信息泄露性能不必要的重渲染、大循环、同步阻塞、未缓存的计算可访问性缺少 alt 文本、键盘导航问题、对比度问题可维护性重复代码、命名不当、缺少错误处理、魔法数字输出结构化报告。输出格式按严重程度从高到低输出严重: 可能导致线上事故或安全漏洞的问题每个问题必须给出复现路径建议: 可能导致长期维护成本的问题给出修改建议疑问: 需要作者确认的设计决策不做强行修改每个问题必须包含文件路径与行号问题类型标签安全/性能/可访问性/可维护性问题描述修改建议格式为“将 A 改为 B”核心逻辑解释 这个 Skill 的价值不在于告诉模型“你要注意安全”,而在于**提供了一个可执行的流程约束**。第一步先拿 diff第二步按风险优先级分组第三步才是具体分析第四步约束输出格式。每一步都是为了让 Agent 的行为更稳定。 反过来如果只写“请认真审查代码”模型每次输出的格式、重点、深度都会不一样。这就是 Skill 和普通 prompt 的差别。 ### 5.3 示例二生成规范提交信息 Skill 另一个适合入门的场景是提交信息生成规则简单、输出格式明确非常容易验证效果。 markdown --- name: generate-commit-message description: 根据暂存区的代码变更生成符合 Conventional Commits 规范的提交信息。当用户输入 git commit、要求生成提交信息时使用。 --- # 生成提交信息 你负责根据 git diff 生成规范的提交信息。 ## 提交类型映射 - feat: 新功能 - fix: 修复 Bug - docs: 文档变更 - style: 代码格式调整不影响逻辑 - refactor: 重构不修复 Bug 也不新增功能 - perf: 性能优化 - test: 测试相关 - build: 构建系统或外部依赖变更 - ci: CI 配置变更 - chore: 其他不修改源码的变更 ## 生成要求 1. 先运行 git diff --cached --stat 了解变更范围。 2. 再运行 git diff --cached 查看具体变更内容。 3. 如果变更同时涉及多个类型选择最主要的一个类型。 4. subject 不超过 50 个字符使用祈使句首字母大写。 5. 如果变更内容复杂在 body 中列出重点变更每行不超过 72 个字符。 6. 禁止在提交信息中包含 AI 生成标记。5.4 示例三依赖安全检查 Skill依赖安全检查是前端项目里很容易被忽略、但出问题代价很高的场景也很适合做成 Skill--- name: dependency-security-check description: 检查项目的第三方依赖是否存在已知安全漏洞并给出升级或规避建议。当用户提到依赖安全、npm audit、package.json、漏洞扫描时使用。 --- # 依赖安全检查 你负责对项目的 npm 依赖进行安全审计。 ## 执行步骤 1. 查看项目根目录的 package.json确认依赖清单。 2. 推荐开发者运行 npm audit --json 获取漏洞数据权限允许时。 3. 如果没有网络或 npm audit 不可用基于你对常见 npm 包安全公告的知识标记高风险依赖。 4. 对每个漏洞按以下维度评估 - 漏洞等级critical/high/moderate/low - 是否处于业务关键路径 - 是否存在已知的修复版本 - 是否有 JavaScript 执行链路真正触达该漏洞 5. 给出处理建议升级到安全版本、使用 patch 临时缓解、或者接受风险并说明理由。 ## 特殊注意 - 不要简单复制 npm audit 的原样输出要按业务影响进行排序和分析。 - 如果一个漏洞无法升级要明确说明风险边界。6. 运行与验证怎么确认 Skill 真正生效写完 Skill 文件后最关心的问题就是Agent 到底有没有按我的 Skill 执行6.1 基础验证第一步确认文件被正确识别ls -la .claude/skills/code-review/如果看到了SKILL.md说明文件结构正确。接着在不同工具里的加载方式略有不同但核心验证思路一致用一个能触发该 Skill 的指令观察 Agent 的行为是否包含 Skill 里定义的步骤。比如验证代码审查 Skillgit add . git commit -m feat: add user login API # 切换到新分支然后让 Agent 审查 git checkout -b test-review然后在 Agent 对话框中输入审查一下当前改动如果 Skill 生效Agent 应该先执行git diff类命令获取变更再按 Skill 里定义的维度输出报告。6.2 判断成功与失败的标准判断 Skill 是否生效不要只看输出格式要看执行过程表现判断输出了结构化的分级报告且包含文件路径和行号Skill 生效Agent 只给了一段泛泛的代码建议没有获取 diffSkill 未生效Agent 回复“我没有权限执行 git 命令”权限配置问题输出的报告格式与 Skill 定义完全无关加载机制问题Skill 没有被识别这里最常踩的坑是Agent 工具本身有权限限制不允许执行git diff、npm audit这类命令。所以在验证之前先确认你的工具是否允许 Agent 执行 shell 命令以及授权的范围。6.3 日志与调试思路如果 Skill 没有生效按以下顺序排查确认文件路径是否是工具约定的目录不同的工具要求可能完全不同以官方文档为准。确认SKILL.md的文件名是否完全正确大小写敏感。确认 YAML frontmatter 是否被正确解析---前后不要有多余空格。确认description中的触发词是否覆盖了你的指令比如你说“帮我看看这代码”但 Skill 描述里写的是“审查代码变更”就可能匹配不上。查看工具日志确认加载 Skill 时是否报错。如果你用的是 Claude Code可以在对话开始时直接问一句“你会哪些 skills”。如果 Skill 被正确加载它通常会在回答里列出可用的技能名称。7. 常见问题与排查方法问题现象可能原因排查方式解决方案Agent 没有按 Skill 执行文件目录不符合工具要求查看工具官方文档的目录约定移动到正确的 skills 目录Skill 始终不触发description 触发词与用户指令不匹配检查描述中包含的任务关键词扩充触发场景描述加入同义词和常见表达Agent 输出内容与 Skill 无关工具不支持 Skills 机制查看当前工具版本和 Release Notes切换工具或改用该工具的规则文件机制Skill 里的脚本无法执行脚本权限不足运行ls -l查看权限执行chmod x scripts/xxx.sh多个 Skill 互相冲突不同 Skill 对同一任务有不同的操作要求检查两个 Skill 的 description 是否有重叠明确职责边界避免一个任务匹配多个 SkillSkill 执行结果不稳定步骤描述过于模糊检查 SKILL.md 中是否给出明确执行顺序把步骤细化到“先做什么、再做什么、最后输出什么”修改 SKILL.md 后不生效工具缓存了旧的 Skill 内容重启工具或重新加载会话重启后再次验证同名任务一个比较容易混淆的情况Agent 明明按照 Skill 的格式输出了但内容质量不高。这通常不是 Skill 加载失败而是 Skill 里的步骤写得不够细。比如只写了“检查安全性”但没说“重点检查输入校验、鉴权绕过、敏感信息缓存”这些具体判断维度模型就会用自己的理解去执行。8. 最佳实践与工程建议8.1 Skill 编写的基本准则从 Addy Osmani 的agent-skills仓库以及实际使用经验来看写好一个 Skill 的核心准则是把隐式经验变成显式规则。很多开发者写 Skill 的时候会写成“请认真分析代码并给出建议”这种正确但没有操作性的废话。这种内容直接放进 prompt 也可以没必要封装成 Skill。好的 Skill 应该回答四个问题这个任务的标准流程是什么先做什么后做什么。每个步骤的输入和输出是什么判断质量的标准是什么什么情况下应该拒绝执行或请示用户一个实操技巧是先不用 Skill单纯让 Agent 执行几次任务观察它的输出哪里不稳定、哪里容易跑偏再把对应的修正规则写进 Skill。这样写出来的 Skill 才有针对性而不是闭门造车。8.2 触发描述要精准description是 Skill 和用户指令之间的桥梁。写得太宽Agent 会在所有任务里尝试加载这个 Skill导致指令冲突写得太窄用户说得稍微拐个弯Skill 就不触发了。推荐写法--- name: test-writing description: 用于为 JavaScript/TypeScript 项目生成单元测试和集成测试。分析被测模块的输入输出、边界条件和依赖关系生成可运行的测试用例。当用户提到写测试、补测试、增加覆盖率、jest、vitest 时使用。 ---关键词覆盖了“写测试”“补测试”“增加覆盖率”等常见表达同时限定了技术栈避免在 Python 项目里误触发。8.3 保持 Skill 单一职责为每个任务拆成一个独立的 Skill不要把“代码审查 测试生成 性能优化”全塞到一个文件里。单一职责的好处在于Agent 可以在正确的时候按需加载。单个 Skill 内容更精简指令噪声更低。后续维护和调整成本低。可以按项目维度动态启用或禁用某些 Skill。一个合理的拆分粒度是一个 Skill 对应一类任务而不是对应一个项目。项目相关的信息应该放在项目级配置里Skill 里只保留通用方法论。8.4 版本管理与团队协作Skill 文件和代码一样应该纳入版本管理。建议# 在项目仓库中管理 git add .claude/skills/ git commit -m docs: update code-review skill checklist # 也可以独立成一个仓库通过脚本或手动方式同步到多个项目团队协作时需要定义谁负责维护 Skill。Skill 和代码一样多人同时修改会产生冲突。比较推荐的方式是由团队里对 AI 工程化最熟悉的同学作为 Skill 维护者其他人提需求维护者统一更新。8.5 安全与权限边界这是最容易忽略的一点。Skill 本质上是一段会被 Agent 自动加载的指令这带来了一个风险如果项目里某个 SKILL.md 是被恶意写入的Agent 可能会按恶意指令执行危险操作。因此在团队项目中不要接受未审查的 PR 中的 Skill 文件变更。不要在 Skill 里写死 API 密钥、token、数据库连接串。Skill 中涉及的 shell 命令要遵循最小权限原则。涉及删除操作、生产环境变更、数据回滚等敏感动作时要明确要求 Agent 先输出方案并征得用户确认而不是直接执行。定期审查项目内的 SKILL.md 变更记录确认没有异常修改。还有一个细节不要授予 Agent“无限制执行 shell 命令”的权限。合理的边界是只允许读取和修改项目内文件需要网络请求或外部 API 调用时单独授权。8.6 从项目实际工作流出发最佳实践永远是“从自己的工作流出发”。Addy 的agent-skills仓库可以作为参考起点但不要照搬。更推荐的路径是记录你过去一周在代码审查、提交信息、测试生成上花费的时间。找出重复性最高、规则最明确的那一类任务。先用传统 prompt 方式跑通流程确认 Agent 能完成。把流程中的关键步骤和约束固化到 SKILL.md。实际使用一周观察哪些步骤还是经常出问题迭代维护。9. 总结与后续学习方向Agent Skills 是目前 AI 编程工具从“聊天助手”走向“可协作同事”的关键一环。它的核心价值不是给模型增加新知识而是把不确定的执行过程变得可预期。回到 Addy Osmani 的agent-skills仓库它给开发者最大的启发是与其收集一堆“让 Agent 变聪明”的提示词不如认真整理项目里最需要稳定输出的任务把它们封装成 Skill。技术含量不高但对工程效率的提升非常直接。如果你准备动手实践建议按下面顺序推进选一个当前最痛苦、规则最明确的任务比如代码审查或提交信息生成。写一个最小可用的 SKILL.md放到工具约定的目录下。用一个真实任务验证触发和输出效果。根据错误输出迭代 Skill 的步骤与约束。稳定后再扩展到第二个 Skill逐步建立你的技能库。后续可以深入的方向包括Skill 与 MCP 工具的组合使用、Agent 在复杂任务中的多 Skill 编排与冲突处理、以及团队级 Skill 治理与版本策略。这几个方向分别对应了“Agent 会做什么”“Agent 按什么顺序做”和“怎么保证做得稳定”三层问题也是接下来一年 AI 工程化实践里绕不开的课题。