1. Agent Skills 到底是什么1.1 从对话助手到可复用技能包先聊个真实的痛点。用过 Claude Code、Codex 这类编程代理的人大概率都有过这种感觉每次让它写前端页面、做代码审查或者整理论文你都得出于习惯把那一大段怎么改、按什么风格、输出什么格式的要求重新敲一遍。对话一长前面的指令还会被冲淡模型越干越跑偏。我一度把这归结为模型记性差直到我真正上手了 Agent Skills 这个概念才发现问题不是模型不行而是我一直在用手工方式反复教它同一件事。Skills 这个功能简单说就是给 AI 代理准备的标准作业程序包。你把一段反复使用的专业操作流程连同它需要的脚本、模板、检查清单、注意事项一起打包放进一个目录。代理在干活的时候会根据任务描述自动决定这个场景该调用哪套技能然后把这个技能包里写好的方法论完整加载进来执行。对我这种天天跟代码打交道的人来说它的意义相当于把资深工程师脑子里那套遇到 X 场景就按 Y 流程处理的经验外置成了可复用的文件。这个功能最适合两类人来学。第一类是前端、后端、数据、测试这些方向的一线开发每天被大量重复性工作占掉时间第二类是把 AI 代理当成生产力工具的内容创作者、研究者、产品经理。它解决的核心问题非常明确怎么让 AI 代理的输出从随机发挥变成稳定交付专业水准。我在实际使用中最大的感受是Skill 不是一个新概念它本质上是把软件工程里的模块化思想嫁接到了提示词工程上。1.2 一个 Skill 的完整解剖图我不太喜欢那些把 Skill 讲得玄乎的文章这东西拆开看其实特别朴素。一个标准的 Skill 就是一个目录目录里最核心的是一个叫SKILL.md的 Markdown 文件剩下的都是它的资源附件。my-skill/ ├── SKILL.md # 技能主文件说明文件 操作手册 ├── scripts/ # 可选的辅助脚本 │ └── check.py ├── templates/ # 可选的模板文件 │ └── report-template.md └── references/ # 可选的参考资料 └── style-guide.mdSKILL.md的头部有一段 YAML 格式的元信息包含两个关键字段name是技能的名字description用一两句话说明这个技能在什么场景下使用。这两个字段就是代理判断现在要不要调用它的依据。元信息下面就是正文正文用自然语言写出完整的操作流程、约束条件、输出要求可以引用目录里的脚本和模板。这里有一个很多人理解偏了的地方Skill 不是一个提示词模板它是一份完整的操作手册加上配套工具。如果你只是把一段提示词存成文件那叫 Prompt 管理不叫 Skill。真正的 Skill 一定包含如何做的结构化步骤而且是可执行的——比如内置一个 Python 脚本来自动检查代码里的常见问题或者内置一份报告模板让模型按固定结构输出。我刚开始用的时候也犯过这个错误把一大段话塞进SKILL.md就以为万事大吉了结果发现效果和直接把话说给代理听没什么区别。1.3 和 Prompt、MCP、Custom Commands 有哪些区别搞清楚 Skill 的边界很重要否则你会不知道什么场景该用哪个方案。我说说自己的理解。Prompt 提醒是最原始的方案每次对话手动粘贴或者通过配置文件自动附加上去。它的缺点是静态的、被动的不管这次任务用不用得上它都占着上下文窗口而且内容一长就会稀释模型对当前任务的注意力。MCP 是另一种东西。它解决的是代理怎么获得外部实时数据的问题本质是给代理接上 API、数据库、工具链。比如一个查天气的 MCP 服务器代理需要的时候会去请求接口拿到数据。Skill 解决的是代理怎么按专业流程完成任务的问题本质是给代理注入一套经验和方法论。一个是数据通道一个是操作规范两者是可以配合使用的——Skill 里可以写遇到报错时调用某 MCP 工具获取日志。Custom Commands斜杠命令则是用户主动触发的你在对话框里输入/review它才执行适合那种我明确知道现在要做什么的场景。Skill 的差异在于它是模型自主触发的代理读懂了任务觉得这个场景匹配某个技能就会自己去加载。我更愿意把它理解为Custom Command 是你手动按开关Skill 是设备自己判断该切换哪个模式。2. Skills 的工作机制模型是怎么想起它的2.1 触发机制的核心description 字段用第一性原理去理解 Skill 的触发机制你得先弄清楚代理拿到一个任务后大脑里发生了什么事。以 Claude Code 这类工具为例启动时它会扫描配置目录下的所有 Skills把它们各自的元信息——主要是名字和 description——加载成一个轻量的技能索引列表。代理在处理具体任务时会把这个列表和用户当前需求做匹配一旦发现某个技能描述和任务场景高度吻合它就会读取那个 Skill 的完整内容然后按照里面的流程开始干活。所以description字段就是整个 Skill 的触发开关它写得不好技能库再丰富也白搭。我见过太多人在这里翻车有人写用于前端开发这种大而空的话结果代理想用的时候发现描述太模糊不知道是该用还是不该用也有人写非常厉害的前端代码审查技能包含大量专业知识和最佳实践这种情绪化的描述对模型没有帮助它需要的是场景判断信息不是形容词。我把写 description 的经验总结成一条公式触发条件加场景边界再加输出承诺。触发条件告诉模型什么时候该用我场景边界告诉模型什么时候不要用我输出承诺告诉模型用了我会得到什么结果。比如我写的代码审查技能的 description 是这样的当用户要求审查 React/TypeScript 代码、提交 Pull Request 前做质量检查、或者修改组件代码后想确认有没有引入回归问题时使用。不适用于 Python 后端代码审查。最后那句不适用于特别重要它能帮模型做负向排除减少误触发。2.2 SKILL.md 正文怎么组织才能被准确执行决定一个 Skill 靠不靠谱的另一个关键因素是SKILL.md正文的结构。模型不像人类给它一段流水账它虽然能读懂但执行起来容易遗漏关键步骤。我推荐在正文里用清晰的多级标题、明确的步骤序号、以及必须和禁止这样的强约束词。我自己的正文一般按照这样几个板块来组织第一块是这个技能在做什么用一两句话说明技能的目标和边界第二块是执行步骤用有序列表把操作流程一步步列清楚每步后面标注输出物第三块是质量标准把验收条件写出来模型交付前要自我对照第四块是常见错误把过去踩过的坑提前写进去从源头规避。这里我要特别强调一个细节正文里所有的步骤描述都应该以产出物为导向。什么意思呢比如检查组件是否存在重复渲染问题就不如检查组件是否存在重复渲染问题如果发现必须在报告中注明具体组件名、触发原因和修改建议。前者是一个动作模型完成了也不知道接下来怎么办后者是一个闭环模型有明确的交付标准。我最初写的几个技能性能不稳定后来发现根因就是正文里检查分析评估这类开放动词太多每个词都给了模型过大的解释空间。2.3 上下文管理为什么技能反而能省 token有朋友问过我一个很尖锐的问题每次调用技能都要把完整的SKILL.md加载进上下文这不会让上下文窗口爆炸吗怎么反而说它省 token这个问题的答案在于代理读取技能的时机。我刚才说了代理启动时只加载技能的索引信息也就是 name 加 description这个信息量极小几十个技能也就几百个 token 的量级。只有当代理判断某个技能有用时它才会把完整的SKILL.md正文读进来。换句话说一个技能平时是不占上下文的只在被需要的那一刻才进场。省 token 是从另一个维度体现的。想象一个没有 Skill 的对话场景你想让代理做一次完整的代码审查你得在对话里逐步描述审查标准、重点检查哪些问题、报告要包含哪些模块、语言风格是什么……这些指令加起来轻轻松松一千多个 token而且每次都要重新说一遍。有了 Skill这些信息全部固化在文件里可能一次只需要几十个 token 的触发描述模型就能按完整标准干活。我实测下来同样的前端审查任务使用 Skill 之后对话轮次明显减少输出质量反而更稳定。当然如果单个技能文件本身写得过于冗长比如正文超过一万字每次触发还是会消耗可观的上文窗口所以写技能时也要克制把精华提炼进去参考资料放外部文件按需读取。3. 从零开始写第一个 Skill3.1 目录结构与 Frontmatter 规范工具的基本使用流程很简单个人级别的技能放在~/.claude/skills/下项目级别的技能放在项目根目录的.claude/skills/下团队共享的技能可以放在 Git 仓库里分发。Codex 系工具有类似的机制只是目录名和配置文件格式略有区别核心思路完全一致。不同工具的加载优先级可能不一样个人目录通常优先于项目目录但如果你遇到行为异常第一件事就是确认技能文件是不是放对位置了。写SKILL.md的头部元信息时有一个加分项容易被忽略有些实现支持给某个技能指定允许使用的工具比如只允许读文件、不允许执行写操作。这个能力对安全敏感型的技能特别有用相当于给技能加了权限沙箱。我建议在写技能时养成一个习惯能限定工具就限定工具能声明适用范围就声明适用范围这不仅能减少模型擅自行动的空间也能让你放心地把一些半自动任务交给代理去跑。3.2 一个前端代码审查 Skill 的完整实现直接上一个我实际在用、效果还算稳定的完整案例这是项目级的.claude/skills/frontend-review/SKILL.md--- name: frontend-review description: 当用户要求审查 React/TypeScript 前端代码、提 PR 前做质量检查、或修改组件后排查回归问题时使用。不适用于后端、Python 代码。 --- # 前端代码审查技能 目标交付一份可直接用于 PR 讨论的代码审查报告覆盖功能正确性、状态管理、渲染性能、可维护性四个方面。 ## 执行步骤 1. 扫描项目代码聚焦用户指定的文件或最近修改的 diff不要全仓扫描。 2. 逐个检查以下要点并记录证据文件名 行号 代码片段 - useEffect 依赖数组是否完整是否存在因依赖缺失导致的闭包陷阱。 - 状态更新是否触发了多余的渲染是否可以从组件树中上移或下沉。 - 列表渲染的 key 是否稳定是否有重复 key 导致的状态错乱。 - 是否直接修改了 props 或全局状态。 3. 对每个发现的问题给出严重等级critical / major / minor并写明修改建议。 4. 生成报告按严重等级排序输出。 ## 输出格式 markdown ## 审查范围 列明文件清单 ## 问题清单 - [ ] [critical] 问题描述 - 位置文件:行号 - 建议具体修改方案 ## 修改优先级建议 按影响面排序质量标准每个问题必须有代码定位和修改建议不允许只写这里有问题。报告使用中文但保留原始代码标识符。如果未发现问题明确说明已覆盖哪些检查点。这个技能的核心设计思想是可取证、可行动、可验收。它要求模型定位到具体文件具体行号这能有效防止模型输出空泛的废话它定义了明确的输出格式模型交出来的报告结构一致我直接就能贴到 PR 描述里它给了质量标准模型在交付前会自行对照检查。 ### 3.3 可执行脚本与模板资源的接入 纯文本的 SKILL.md 已经能解决很多问题但真正让技能高级起来的是接入脚本和模板。我举个例子上面的前端审查技能如果配一个提取 diff 的脚本效果会好很多。比如写一个 scripts/git_diff_files.sh bash #!/usr/bin/env bash # 获取当前分支相对主干分支的变更文件列表 branch${1:-main} git diff --name-only $branch...HEAD -- *.ts *.tsx | head -50然后在SKILL.md的步骤一里写明调用 scripts/git_diff_files.sh 获取变更文件清单基于该清单确定审查范围。这样一来模型就不用自己猜该看哪些文件脚本给它提供了一个客观可靠的依据。类似的思路还能用在数据提取、日志检索、格式化校验等场景。模板资源的价值则体现在输出一致性上。比如我写论文整理类的 Skill 时会把一张固定的报告模板放进templates/目录明确要求模型按模板填写。这样不管任务执行了多少次产出的文档结构始终统一。我自己的经验是任何你希望每次都长一样的内容都值得固化成模板任何你可以用程序精确计算的内容都值得写成脚本让模型调用。技能文件里写的应该是判断规则和操作流程而不是让模型每次都从头推导一遍。4. 找现成 Skills 的渠道与筛选心得4.1 官方市场与 GitHub 生态不是所有技能都得自己写社区里已经沉淀了大量现成的 Skills这也是当时这个功能火得这么快的原因之一。获取渠道大致有这么几类。第一类是官方渠道。Claude 系的官方文档里提供了 Skills 的规范说明和示例是学习书写规范最好的入门材料。Codex 的官方文档也有关于自定义指令和技能类功能的使用说明。官方渠道的意义不只是下载现成技能更重要的是里面会说明当前版本支持哪些能力、不同字段的定义和边界这些信息社区里往往是二手甚至三手的容易失真。第二类是 GitHub。直接在 GitHub 上搜 awesome-claude-skills 或者 claude skills 就能找到大量聚合仓库很多开发者把常用技能开源出来。GitHub 的好处是你能直接看到源码和更新历史坏处是质量参差不齐。我的经验是优先看 star 数高、最近还在维护的仓库那些几个月不更新的技能很可能已经不适配新版本的工具了。另外GitHub 本身也提供云端开发环境和 AI 助手相关的能力用 GitHub 账号体系来同步和管理团队技能在协作场景下非常方便。4.2 社区聚合平台怎么逛官方市场和 GitHub 之外还有不少社区维护的技能集散地。这些平台会把技能按场景分类标注作者和维护状态搜索起来比在 GitHub 上大海捞针高效得多。我逛这类平台时有一个固定流程先看技能的最近更新时间和下载量再看SKILL.md的 description 写得好不好最后打开源码确认它是纯提示词还是有配套脚本。这里要提醒一点任何一个开放下载平台上的技能本质上都是别人电脑上的文件安全性要自己把握。优先选择那些源码公开、结构清晰、没有各类加密混淆文件的技能。如果一个技能文件里塞了大量压缩数据或者说要用某种私有二进制运行时我建议直接放弃。技能文件是明文运行的理论上你可以通读全部内容再决定用不用——这是个巨大的安全优势别浪费这个优势。4.3 筛选现成 Skills 的五条标准我把自己的筛选经验总结成五条标准分享出来给你参考。第一条description 是否精确一个能用一句何时用、何时不用说清场景的技能作者通常是认真思考过的第二条是否有可执行的产物标准技能正文里有没有把输出格式、验收条件写清楚空泛的技能装了也不会好用第三条是否依赖过重的环境比如某个技能要求一堆 Python 包、Node 版本、系统服务装上之后维护成本会非常高除非它不可替代否则别碰第四条是否有维护记录看更新日志和 issue 的处理情况长期没人管的技能早晚会失效第五条冲突情况新技能是不是和你已有的技能在 description 上高度重叠重叠会导致代理调用时犹豫甚至调错。我遇到过最典型的失败案例是装了一个号称全能代码优化的通用技能结果它在绝大多数场景都不会被触发偶尔被触发时输出和建议跟我自己的代码审查技能打架。删掉之后世界安静了。装技能之前多花两分钟看源码比装完后悔再排查省得多。5. 四个高频实战场景的 Skill 拆解5.1 前端开发加速说一个我日常最依赖的场景。现代前端开发有一个很有意思的矛盾框架越来越多、工程链越来越复杂但日常干的活其实高度重复——新页面、新组件、状态管理、接口对接、样式调整。这部分工作恰恰是 Skills 发挥价值最大的地方。我写了一个Frontend 开发助手技能它的SKILL.md里固化了项目的技术栈约定、组件代码风格、目录组织结构以及新组件创建时要走的完整流程先定义 props 类型、再写数据获取逻辑、再写渲染逻辑、最后补样式和导出。技能里还放了一个templates/component.tsx模板文件组件的基础骨架都写在里面模型每次新开页面都会按这个骨架来生成。另一个实用场景是优化移动端适配。我会写一个专门的响应式排查技能让代理逐屏检查每个页面的断点表现、图片尺寸、触控目标大小并按一套固定清单报告问题。这种技能有效的原因在于适配问题有一套相对客观的检查标准固化成技能后代理就不会像没有标准的对话那样东看一眼西看一眼。5.2 论文写作与学术稿件整理写论文这个场景在热搜里出现频率很高我也专门做过这类技能。它解决的是学者和研究生的一个常见痛点用 AI 写学术内容不是生成不出来而是生成得太不像学术作品。模型默认输出的语言风格是流畅的公众号风用在论文里就是灾难。我的论文技能里写死了几条铁律第一摘要部分必须按照研究背景—问题—方法—结果—结论五要素组织且总字数不超过三百字第二文献综述部分禁止使用无出处的断言每一句涉及前人工作的表述都要标注引用来源第三论文正文的论证结构必须采用领域现状—现有方法不足—本文方法—实验验证的推进方式第四所有提交内容必须按目标期刊的参考文献格式统一格式。技能文件里还放了一份几万字的研究领域背景资料作为参考资料模型写作时可以按需检索不用每次都临时编。这里面有一个值得注意的技术细节论文类技能对引用规范的约束必须放在显眼位置而且要写得很具体。因为模型特别容易生成虚拟引用这是 AI 辅助写作最大的风险之一。技能里专门有一条当引用某篇文献时必须使用 references/ 目录里的文献库进行校验若文献库中不存在该文献请在文中标注待核验。从机制上把编造引用的可能降到最低。5.3 分镜脚本生成分镜脚本是视频创作里的一个专业环节在热搜词里也出现了说明不少人已经在跑这个场景。在没有技能之前让 AI 写分镜脚本的结果通常是概念是有的但写出来的镜头语言外行——不会区分景别、不理解运镜逻辑、不清楚一场戏怎么拆成多个镜头。我的分镜技能把专业知识全部固化到了SKILL.md里。它在执行步骤中明确要求第一步确定叙事段落和情绪基调第二步拆解每个段落的镜头序列每个镜头必须标明景别远景/全景/中景/近景/特写、运镜方式固定/推/拉/摇/移/跟、时长、画面内容、台词或旁白、音效和音乐第三步输出标准格式的分镜表格。技能里还内置了常见的镜头语言速查表比如表现角色孤立感使用远景加慢推表现紧张情绪使用手持运镜加快速剪切模型生成时会主动参考这些规则。这类技能的火爆让我意识到一个趋势Skills 的应用边界正在从纯代码领域向外扩展。代码审查、论文写作、分镜脚本、影视策划、教学设计凡是有一套可描述的流程规范的领域都适合用技能来封装。写技能的人不需要会写代码只需要能把自己行业的操作流程清晰地文本化。5.4 安全审计防御向我在这里要特别强调一下安全审计这个场景的边界。网上流传的所谓自动挖洞 skills我强烈不建议去碰利用 AI 开发攻击性工具、挖掘未授权系统漏洞既踩法律红线也违背技术和 AI 使用的伦理底线。我用的安全类技能是纯粹的防御场景对自己负责的代码库做安全自查在攻击者之前发现并修复问题。这类技能的价值在于把安全审查的最佳实践检查清单沉淀下来。比如检查 SQL 拼接、检查不安全的反序列化、检查缺失的鉴权判断、检查硬编码凭据、检查依赖库的已知漏洞等等。我的安全审查技能里有一条核心约束本技能仅用于审查用户有权审计的代码发现漏洞后必须同时给出修复建议禁止演示如何利用漏洞。有了这条约束技能既能辅助防守方的工作又不会成为攻击脚本的生成器。安全审计技能和前面其他技能的关键差异在于它需要更强的置信判断宁可漏报一些低风险项也不能误报引入虚假的安全感。所以技能正文里我特别强调了所有风险等级为 critical 的判断必须有三处以上证据支撑用机制抵消模型过度自信的倾向。6. 常见问题与排查技巧实录6.1 Skill 不被触发怎么办这是新手遇到最多的问题技能文件放对了格式也写好了但代理就是不用。我自己的排查顺序是这样的。先检查技能目录是否在正确的读取路径下。个人技能放在用户目录的.claude/skills/项目技能放在项目根目录的.claude/skills/。如果放错位置工具根本不会扫描到。然后检查SKILL.md的文件名大小写和拼写错了同样不会被正常识别。再检查元信息格式YAML 部分的字段名拼写、缩进、description是否完整任何一个解析错误都会导致整个技能失效。如果这些都正常问题通常出在 description 写得不好。我刚才反复强调过description 是模型判断何时调用的唯一依据它写得太宽泛或太具体都容易出问题。太宽泛的场景描述会让模型不确定这个技能是否适合当前任务太具体的描述又会让模型在某些本该用到的变体场景下放弃使用。我自己的方法是模拟两个场景读 description 时问自己什么任务会触发它再问什么任务不该触发它两个问题都有清晰的答案才算合格。6.2 脚本运行报错怎么定位技能里接入了脚本之后最常见的问题是脚本执行报错。很多人和我说脚本在自己终端里跑得好好的代理一调用就出错。这里有个关键知识代理执行脚本时的工作目录不一定是你技能目录所在的位置它通常沿袭当前会话的项目根目录。所以你的脚本里所有相对路径都可能失效。解决方案很简单脚本开头写一段稳健的路径处理逻辑。比如在 Python 脚本里用Path(__file__).resolve().parent定位脚本自身所在目录再基于它拼接资源文件路径。另一个常见问题是没有给脚本设置执行权限chmod x一下否则代理调用时会直接被拒绝。还有一个经验脚本应该设计成能接受参数或读取标准输入的交互模式而不是把逻辑写死在代码里这样技能才能在不同项目里复用。最后如果脚本本身就依赖第三方库最好在技能目录里附一个简单的启动提示写在SKILL.md里让代理执行前检查依赖是否齐全。不要让它自行猜测如何安装依赖否则它可能给你装出一堆乱七八糟的版本。6.3 多 Skill 冲突与优先级管理技能装多了另一个问题会浮出水面多个技能的 description 互相重叠代理不知道选哪个。比如你装了一个前端审查技能又装了一个代码质量检查技能触发前者的时候代理可能加载了后者输出风格和检查重点都变了你会觉得技能失效了其实是被另一个技能顶掉了。管理多技能我有两条原则。第一技能库保持克制个人维护的技能数量控制在十到二十个以内每个技能都要有明确的不可替代的使用场景第二同类技能的 description 必须写入排除边界例如两个审查类技能一个写明仅处理 React/TS 项目另一个写明处理 Python/后端代码从描述上彻底划清管辖范围。冲突问题多数是设计问题而不是工具问题靠严谨的 description 规划就能解决。6.4 团队协作时的 Skills 管理最后聊聊团队场景。当技能从个人目录迁移到团队仓库要特别注意版本管理和兼容性。我的建议是把团队技能放在一个独立仓库中维护用 Git 管理变更记录每次更新都写清楚 changelog。新成员加入时只需要克隆并配置好路径变量不用手动复制文件效率和正确率都高很多。团队技能还要做定期审计。因为工具版本在升级模型能力在变化半年前很好用的技能现在可能已经失效或者有了更好的写法。我习惯每季度把团队技能库整体过一遍检查每个技能的 description 是否仍然准确、正文里的工具名和命令是否仍然有效、没有被废弃的脚本引用。这条习惯看起来不起眼但它能让技能库长期保持在一个可用且可信的状态不会被历史包袱拖垮。踩过几次坑之后我现在对 Skills 的态度是它是当前 AI 代理生态里性价比最高的一种自定义方式因为它的学习成本低、机制透明、完全文件化、可版本控制。但它的上限也取决于你能不能把自己的专业判断变成结构化的操作流程。说到底AI 代理的 Skills 真正封装的不只是提示词或脚本而是你脑子里的那套怎么干活的思维方式。花点时间把自己的经验沉淀成技能得到的回报远不止省下的那几次重复输入。