1. 当skills从下载热词变成 agent 工作流的基本单元最近一个月我陆续把自己日常用的 AI 编程工作流整个重写了一遍起因就是skills这个词反复出现在各类 Release 说明、社区帖子和热词榜单里。搜索前端开发 skills、分镜 skills、论文写作 skills 的人越来越多大家其实都在找同一个东西让 Claude Code、Codex 这类 agent 在启动任务时自动加载一组可复用的能力而不是每次把一大段提示词粘来粘去。这篇内容我想从 agent skills 的第一性原理出发讲到实际落地时怎么安装、怎么自己写、怎么避坑最后给出一套我实测过的工作流组合思路。1.1 我为什么把注意力从找插件转向攒 skills先说一个直觉。在 skills 这个概念流行起来之前我的 agent 工作流基本就是一套超长 system prompt外加一堆复制粘贴的模板段落。比如做前端代码审查时我会把 ESLint 规则、代码风格要求、输出格式全部写进提示词里换到一个写论文的场景又得重新写一套关于文献格式和段落结构的提示词。时间一长就会发现这套方式的维护成本高得可怕改一个规则要同步修改所有历史模板两个项目共用同一套提示词时经常互相污染A 项目的审查规则会莫名其妙出现在 B 项目的文档生成任务里。后来我开始尝试把能力拆成独立的 skill前端审查是一个 skill论文结构检查是另一个 skill分镜脚本生成又是一个 skill。每个 skill 拥有自己独立的描述文件、脚本和参考资源agent 只有在任务命中时才会加载对应的那部分内容其他时候完全不占用上下文。这个转变带来的体验提升非常明显——上下文窗口从什么都要放变成用到什么才放什么规则的修改也收敛到单个目录不再动辄改一堆模板。1.2 skills 大火背后的真实需求复用、隔离、可组合为什么skills这个词能在短时间内变成搜索热词而且搜索的人明显不只是开发者还有剪辑、文案、运营这些岗位我的理解是大家真正需要的不是再找一个更强的模型而是把某一类任务的最佳实践固化下来下次直接调用。skills 恰好就是这个载体。它的价值可以拆成三部分复用同一套审查规则、同一份分镜模板、同一个论文格式检查流程写一次就能在多个项目里反复使用。隔离不同任务的知识互不干扰。论文 skill 里不会带着前端代码风格规则前端审查 skill 里不会出现文献引用格式。可组合一个复杂任务可以由多个 skill 接力完成比如先让任务拆解 skill把论文写作拆成文献整理、摘要重写、格式检查三步再分别触发对应的技能包。正是这三条让 skills 从一个下载热词变成了 agent 工作流的基本单元。接下来我想先从原理层面拆一下为什么一个看起来只是文件夹文档的东西能产生这么大的差异。2. 先从第一性原理看透 skill 的加载与调用机制网上关于 agent skills 的深度分析文章不少我看过一篇标题带first principles deep dive的拆解自己也做了不少实验最后形成了一套比较朴素的理解skill 本质上不是一个程序插件也不是一段 prompt而是给 agent 的一本工作手册 一套辅助工具的组合。理解清楚这一点才算真正知道怎么用、怎么写。2.1 一个 skill 本质上是什么目录、描述文件与可执行脚本我习惯把一个 skill 理解成三层结构。拿我写过的前端代码审查 skill 举例它的目录长这样frontend-review/ ├── SKILL.md ├── scripts/ │ ├── check_env.sh │ ├── run_lint.sh │ └── format_report.js └── resources/ ├── rules/ │ ├── vue_style.md │ └── react_style.md └── templates/ └── report_template.md这里的SKILL.md是核心入口负责告诉 agent我是干什么的、什么时候该用我、用我的时候应该遵循什么流程。scripts/放真正可执行的逻辑比如跑 ESLint 的脚本、生成格式化报告的工具。resources/放一些参考材料比如风格规则、输出模板它们不会被一次性全部塞进提示词而是由 agent 按需读取。换句话说SKILL.md面向模型scripts面向执行环境resources面向具体场景。三者合在一起才构成一个完整的 skill。2.2 agent 是怎么看懂 SKILL.md 的这里有个关键机制agent 并不会把每个 skill 的全部内容都加载进上下文。平时 agent 会看到一个技能列表列表里主要是每个 skill 的名称和描述当用户提出的任务和某个描述高度匹配时agent 才会真正读取对应目录下的SKILL.md和相关的脚本。这就像一家餐厅后厨平时挂在墙上的菜单技能列表只看菜名和简介客人点了宫保鸡丁之后厨师才会去翻对应的菜谱SKILL.md、拿对应的食材resources和工具scripts。这个设计意味着描述文件写得好不好直接决定 skill 会不会被正确唤醒。我见过很多不生效的 skill问题不是脚本写错了而是SKILL.md里的描述写得太抽象agent 根本判断不出来这个任务应该用它。2.3 为什么说 skill 比 prompt 更结构化比插件更轻量把 skill 和传统方案摆在一起对比会更直观对比维度长 PromptSkill插件加载时机每次对话固定加载按意图匹配后加载常驻运行环境上下文开销高长期占据窗口低命中才注入中需维护运行进程独立性差多任务互相污染强目录级隔离强模块级隔离扩展能力无只能改文字可带脚本和资源完整编程接口上手门槛低低写文档即可高需要了解工具链从这个表能看出skill 精准地卡在结构化程度够用和上手门槛足够低之间的位置。它不需要你写完整的程序接口只需要组织好目录和描述文件必要时再配几个脚本同时它又比纯 prompt 更可控因为有独立的文件边界和调用触发机制。真正跑通之后你会觉得它就像一个可随时翻阅的工作手册而不是一套僵硬的自动化程序。3. 去哪里找靠谱的 skills官方市场、GitHub 仓库与第三方站点聊完原理进入实操。很多人搜索skills 推荐skills 下载平台有哪些说明第一步都会被卡在资源获取上。我把自己常用的几个渠道整理了一下也顺带说说怎么判断一个 skill 值不值得装。3.1 官方市场与内置技能包目前主流 agent 基本都有自己的技能分发渠道Claude 和 Codex 都有官方市场或官方仓库你可以在里面浏览分类、看使用说明一键添加到本地配置。这些官方渠道的最大好处是目录结构统一依赖说明清楚更新维护稳定。以我常用的 Claude Code 为例装好对应的 agent 环境后本机会有一个 skills 配置目录市场里的技能包本质上就是被下载到这个目录。Codex 的做法也类似很多技能以仓库形式托管安装时通过配置声明让 agent 能够检索到。至于其他一些工具比如 Reasonix安装入口通常在它的插件/技能面板里支持通过 zip 或 git 仓库导入。3.2 GitHub 上值得关注的 skill 合集真正大量且免费的资源还是聚集在 GitHub。社区里有一类专门收集整理的合集仓库比如以awesome开头的列表会按前端、后端、写作、设计、数据分析等方向列出各种 skill 的仓库地址。还有一些个人开发者把全套 skill 打包成一个大仓库比如社区里流传度比较高的 Superpowers 系列里面既有通用任务技能也有专门针对编程场景的技能包。在 GitHub 上挑选 skill 时我的标准是star 数只做参考最近 commit 时间和 README 完整度更重要。因为 skill 本质是文档驱动的项目如果作者半年没更新很可能已经跟不上对应 agent 的格式变化如果 README 连目录结构前置依赖使用示例都没讲清楚装进去大概率是给自己找麻烦。3.3 第三方下载平台的甄别标准除了官方市场和 GitHub还有一些专门的技能下载站点提供打包好的 zip 或按 npm 包分发的 skill。这类平台的优点是一站式浏览缺点则是质量参差不齐。我踩过几次坑之后总结出几条甄别标准是否包含 SKILL.md没有入口描述文件的目录基本可以直接放弃。是否声明依赖比如脚本需要 Node 18、Python 3.10必须写清楚否则装完就是一堆报错。是否包含示例至少应该有一个输入输出样例让你能预判它的行为。是否有许可证和作者信息涉及商用场景时这条很重要别到后面才发现不能用于商业项目。3.4 从下载包到本地激活的最小流程如果你之前完全没接触过 skill 安装我给你一个通用最小流程下载 skill 的压缩包或 clone 仓库到本地。解压后检查是否有SKILL.md文件如果没有换下一个。把整个目录放到当前 agent 的技能目录下不同工具路径可能不一样可以通过配置文件或管理命令确认。重启 agent或在会话里执行重新加载技能的操作。用一个简单任务测试触发比如直接说出 skill 描述里的关键词看它是否按预期输出。第一次跑通这个流程之后后面基本就是熟练工了。但安装只是起点真正的重头戏是学会自己写一个适合自己的 skill。4. 手写一个前端代码审查skill 的完整过程理论再多不如动手写一个。我以自己最常用的前端代码审查skill 为例从定义场景到验证迭代完整拆一遍。这个 skill 的核心任务很简单接收一个前端仓库或 PR diff按照既定规则检查代码输出一份结构化的问题清单。4.1 定义触发场景和输入输出在动手建目录之前先想清楚三件事什么时候该唤起这个 skill、给它什么、它要产出什么。我的定义是这样触发场景用户要求对前端项目做代码审查、检查代码质量、处理 lint 报错。输入仓库目录路径、PR diff 内容或者一组指定要检查的文件路径。输出Markdown 格式的问题清单包含文件位置、问题等级严重/一般/建议、问题描述、修改建议。这个定义看起来简单但非常关键。因为 agent 就是靠这段描述来决定什么时候该加载这个 skill。描述里最好直接带上前端、审查、lint、代码质量这类高频触发词同时用一句不要用于非前端代码做反向约束。4.2 组织目录SKILL.md、scripts 与 resources我最终整理的目录结构在 2.1 那一节已经展示了这里重点说目录组织思路。SKILL.md是整个 skill 的导航中心它的正文一般包含--- name: frontend-review description: 用于前端项目代码审查支持 Vue/React 项目执行 lint 与类型检查输出结构化问题清单。不要用于后端代码或文档审阅。 --- # 前端代码审查 ## 适用场景 当你需要检查前端代码质量、处理 lint 错误或审查 PR 时使用。 ## 使用步骤 1. 确认输入是否包含仓库路径或文件列表否则先询问用户。 2. 检查环境依赖运行 scripts/check_env.sh确认 Node 与 npm 可用。 3. 运行 scripts/run_lint.sh 获取 lint 输出。 4. 读取 resources/rules/ 下对应框架的规则结合 lint 输出整理问题清单。 5. 按 resources/templates/report_template.md 输出结构化报告。 ## 注意事项 - 不修改源码只输出审查报告。 - 若 lint 命令缺失提示用户安装依赖不要擅自安装全局包。scripts/run_lint.sh是一个很薄的封装脚本做的事情就是进入项目目录执行npx eslint --ext .js,.ts,.vue .然后把结果保存到一个临时文件方便 agent 后续读取。resources/rules/下则是我根据团队规范整理的检查要点比如 Vue 项目里 props 是否显式声明默认值、React 项目里 hook 依赖是否完整。资源文件不会被一次性读入上下文agent 需要用哪条规则才会打开对应文件这是节省 token 的关键设计。4.3 写描述文件的注意事项SKILL.md 看起来简单但写起来有四个容易踩的坑第一句话就要落到场景agent 的匹配逻辑通常会优先扫描描述的开头部分所以把前端代码审查放在第一句比放在第五句效果好得多。描述不要写成广告写这是一个功能强大的审查工具毫无意义要写什么时候用、能做什么模型不读形容词只读场景和动作。一定要加反向约束我见过太多因为描述没写不要用于 XX导致误触发的案例反向约束可以有效降低误唤起率。依赖越具体越好直接写需要 Node 18 以上、npm 8 以上比写需要较新版本的 Node更有价值agent 才能做环境检查。4.4 用真实项目验证并迭代写完目录和文件 ≠ skill 可用验证过程才是真正决定质量的部分。我的习惯是先在一个小型练习项目上测试再上真实项目。第一次跑的时候我的 skill 暴露了三个问题。第一个是scripts/run_lint.sh在项目没有安装依赖的情况下直接失败后来我在脚本里加了依赖检查缺依赖时不报错而是输出引导信息。第二个是报告模板太啰嗦每条 lint 错误都展开一大段解释导致输出非常冗长后来我改成问题等级 文件位置 单行描述 修改建议的精简格式。第三个是 agents 偶尔会忽略resources/rules/里的规则我去检查发现是因为SKILL.md里没有明确告诉它必须读取规则文件再生成结论调整描述措辞后行为就正常了。这个迭代过程给了我一个重要教训skill 的行为完全由描述文件引导脚本只是辅助想让 agent 做什么必须写进文档里而且要写得足够明确。5. 安装、启用与排查让 skill 真正运行起来如果说写 skill 是造轮子那安装就是装轮子。很多人卡在这一步抱怨 skill 装完不生效。下面我把不同 agent 的安装入口、验证方法以及我踩过的坑集中讲一下。5.1 不同 agent 下的安装入口不同的 agent 对 skill 的加载方式不太一样。以我用的环境为例Claude Code 这类工具有一个技能管理入口你可以通过交互式命令查看当前已加载的技能列表也可以直接把下载好的 skill 目录放到本机的配置目录里。Codex 则更倾向仓库式管理你可以把技能仓库加入配置文件agent 启动时会自动建立检索索引。其他工具比如 Reasonix虽然界面不同但逻辑类似都是在设置面板里指定技能目录。Agent我实测的安装方式需要留意的地方Claude Code通过技能管理命令 / 直接放配置目录确认路径没有被版本隔离机制覆盖Codex配置文件声明技能仓库 / 导入 zip仓库格式是否符合 skill 规范Reasonix设置面板导入 / 插件中心安装安装后留意是否需要重启会话这里我建议所有人在安装前先做一件事找到官方文档里关于 skills 路径的说明。因为版本更新频繁路径和命令可能都在变网上教程不一定对应你当前的版本。宁可多花十分钟读文档也不要凭记忆猜路径。5.2 如何确认 skill 已生效确认生效最好的方法是在对话里做一个诱发测试直接输入和 skill 描述高度相关的任务观察 agent 的输出是否符合预期。我自己的验证链条是打开会话输入你现在加载了哪些技能或直接看技能管理界面确认目录被识别。输入一个命中描述关键词的任务比如帮我审查一下这个前端目录的代码质量。查看输出的细节如果它真的读取了resources/rules/下的规则、跑了脚本、按模板输出说明 skill 完整生效。如果行为不对打开调试日志看 agent 有没有尝试读取SKILL.md。这套验证方法虽然原始但比任何理论都管用。5.3 我踩过的坑名称冲突、描述误触发、依赖缺失安装和使用过程中我实际踩过四个比较典型的坑拿出来分享同名的 skill 冲突我从两个渠道分别装了一个名为frontend-review的技能结果其中一个总是覆盖另一个。后来我把本地自研的 skill 目录改成了带命名空间的格式比如myteam-frontend-review问题才解决。描述太宽泛导致误触发早期我写过一个描述为帮助处理代码相关任务的 skill结果几乎所有代码任务都会尝试加载它上下文直接被塞满。加上反向约束、收紧关键词之后触发频率才恢复正常。运行时依赖缺失某个 skill 的脚本用到 Node 16 之后才支持的语法但我的环境还是 Node 14脚本直接崩溃。后来我坚持在 skill 的SKILL.md里写明前置条件并在脚本开头做版本检查不满足条件就输出友好提示。目录结构变更导致不加载agent 升级后技能目录从旧路径迁移到了新路径旧的绝对路径失效。从那以后我再也没有硬编码过目录路径全部通过 agent 自身提供的路径变量来引用。6. 把 skills 组合成完整 workflow论文、分镜与安全巡检如果说单装一个 skill 是加分项那把多个 skill 组合成一条完整的 workflow才是让效率产生质变的关键。我分别挑了论文写作、视频分镜、安全巡检三个典型场景讲讲我是怎么组合的。6.1 论文写作技能组合写论文看起来是个纯然语言任务但把它拆成技能组合之后整个流程会清晰很多。我的组合是三个 skill 接力文献整理 skill接收论文主题输出一份结构化的文献清单并标记每篇文献的核心观点和可引用段落。摘要重写 skill把文献里的长段落改写成适合放进论文的简洁表述同时保留原始出处。格式检查 skill扫描论文全文检查标题层级、参考文献格式、图表编号是否一致。这三个 skill 是分步触发的前一个的输出会成为后一个的输入。组合使用的时候有个细节不要让 agent 同时加载全部三个 skill而是通过第一个 skill 的输出去触发第二个避免一次对话塞入太多规则。我个人的经验是先让任务拆解 skill或者直接让 agent 自己规划明确每一步的输出文件中间结果写入本地 Markdown下一个 skill 再读取这样上下文压力小很多。6.2 视频分镜生成技能组合分镜 skills 也是热词之一很多做短视频、宣传片的人都在找。我写过一个分镜 skill输入是一段故事大纲输出是一份分镜表。它的核心价值不在会说话而在输出结构固定每一条分镜都包含镜头号、景别、时长、画面描述、台词、音效建议。组合使用时我会在前面加一个脚本拆解 skill先把大纲按时间轴切成场景段落中间是分镜生成 skill按段落生成分镜表后面再加一个镜头参数补充 skill给每个镜头补上焦距、机位、打光方向等细节。这套流程的直接效果是过去需要一个下午来完成的分镜初稿现在十几分钟就能出一版可讨论的草稿。当然分镜 skill 的质量上限取决于模板设计水平模板越具体输出越接近可用状态。6.3 安全巡检类技能的使用边界搜索热词里还有一类自动挖洞 skills的内容。这里我要明确一个边界凡是涉及安全测试的技能都只能在授权范围内使用比如自己的项目、公司授权的测试任务、合法靶场环境。我把这类需求封装成了安全巡检 skill它做的事情其实很常规调用已有的漏洞扫描工具、汇总扫描结果、按风险等级生成报告而不是提供任何漏洞利用能力。合规使用的要点我写在三个地方SKILL.md开头显著位置标注仅限授权环境使用。脚本只允许调用标准扫描器不包含任何绕过认证或利用漏洞的代码。每次运行前先检查是否存在授权文件或书面确认记录。6.4 组合使用的优先级与上下文管理把多个 skill 串起来之后最需要管理的其实是优先级和上下文。我的经验是先骨架后血肉先用一个任务拆解类的 skill 把整体流程分成几步再逐步触发具体 skill不要一开始就把所有 skill 的描述都暴露给 agent。中间结果落盘让 agent 把每步结果写入临时文件而不是全部留在对话里避免上下文膨胀后输出质量下降。只保留必要的 skill每个工作流最多三个 skill 同时在线多了反而会让 agent 陷入选择困难。7. 发布自己的 skill命名、文档与版本管理如果你自己写了一个还不错的 skill并且想分享出来给团队或者社区用那最后这一步就很重要。发布不是丢一个文件夹上去那么简单命名、文档、版本这些问题都会直接影响使用者体验。7.1 命名和描述怎么写更容易被检索到命名建议用动词对象的组合比如review-frontend、generate-storyboard、format-paper这样既清楚又能被搜索到。描述方面把高频触发词放前面补充使用场景和反向约束格式上最好固定成用于 XX 场景支持 XX 操作不适合 XX 情况的三段式。我见过一些命名很随意的 skill比如my-tool、helper这种名字不仅难以检索还容易和别人的技能冲突。发布前先在社区里搜一下确认没有同名技能能省去后续很多麻烦。7.2 本地测试清单发布前我会过一遍这个清单目录结构是否完整是否包含SKILL.md文件名大小写是否正确。SKILL.md是否能被当前 agent 正常解析并触发。所有脚本是否在一个全新环境里能跑通前置依赖是否全部声明。是否包含一个示例输入和对应输出方便使用者快速验证。是否写清楚许可证、作者信息和更新日志。7.3 版本管理与更新策略skill 虽然简单但版本管理不能省。我习惯在 frontmatter 里加一个version字段每次更新都递增。修改description要格外谨慎因为描述一变agent 的触发行为可能完全不同所以建议在 changelog 里明确标注描述修改会导致触发逻辑变化。更新脚本时同步更新 README 和测试样例这条我强调再多都不为过。很多人只更新脚本结果文档和实现脱节使用者照着文档操作却得不到预期结果最后反而拉低了对这个 skill 的评价。最后再说一点个人体会skill 这个东西不要一上来就往大了做先从自己重复率最高的那三五个任务入手把它们封装成技能包。我在这段时间里最大的收获不是某个技能本身而是养成了一种习惯——凡是重复做过三次以上的任务我就会想是不是该把它沉淀成一个 skill 了。这种积累方式比任何一次大而全的技能封装都更实际。如果你也想给 skill 加一个低成本的维护机制可以在SKILL.md末尾加一个常见问题小节让 agent 遇到不确定的输入时先去读 FAQ 而不是直接乱猜这一招能让技能在真实场景里的稳定性提高不少。