搞Agent开发的朋友最近应该快被“skills”这个词刷屏了。不管是Claude Code里的skills目录还是Codex、Cursor这些工具里冒出来的技能包又或者社区里突然蹿红的Superpower Skills、Pi Agent、Hermes Agent风向已经很明显光有强大的模型还不够怎么让Agent稳定复现“某一种专家工作流”才是2025年真正拉开差距的地方。Skills就是这套打法的核心载体。我最早接触skills这个概念是在折腾Claude Code的插件化配置时。那时候大家还管这叫“命令”或“自定义指令”本质上是把一段很长的、针对特定任务的prompt固化下来让Agent在需要时主动调用。后来各家Agent框架陆续把这个机制标准化形成了今天看到的“SKILL.md 脚本/资源文件”的目录结构。这篇文章我就从“agent-skills”这个项目名切入把这些天踩过的坑、拆过的包、写过的技能从头到尾梳理一遍。不管你是刚开始接触Agent开发还是已经在搞harness和插件体系这篇应该都能给你点实在的东西。先说清楚一个基础认知skills到底解决什么问题。打个比方大模型像个天赋极好的实习生什么都能聊两句但你让他独立完成一份严谨的LaTeX排版稿件、一组结构化的前端组件、一份符合论文规范的图表他每次的发挥都会有波动。Skills做的事情就是把这个“实习生的上岗手册”写出来把专家怎么分步骤、怎么检查、怎么规避常见错误的方法论做成一份可复用、可分发的能力包。这样Agent在遇到对应任务时不再是从零开始“灵机一动”而是按手册里的标准流程走一遍输出质量自然就稳了。理解了这一层后面看任何skills项目你都能快速判断它到底值不值得装。1. Skills的概念拆解它和Prompt、Agent、Tool到底什么关系关于skills社区里讨论最热烈的问题之一就是“skill和agent的区别”还有“harness和agent的区别”。这些概念确实容易混因为各家文档叫法还不统一。我按自己的理解给你捋一遍不一定跟所有框架的官方定义完全一致但理清这层关系后你看任何相关项目都会顺很多。1.1 Skill与Prompt从一次性指令到可复用能力Prompt本质上就是个文本输入你跟模型说“帮我写一个Python脚本做数据清洗”这是一次性交互。下次你再想让模型干同样的活还得重新说一遍而且换个说法输出质量可能就变了。Skills则不一样它把“数据清洗”这件事拆成了一套固定流程检查哪些列、用什么规则处理缺失值、输出什么格式的报告全部写在SKILL.md里再附带几个实际的参考脚本。Agent识别到任务匹配后会按这套流程执行而不是每次重新组织语言。用大白话说Prompt是“你告诉模型怎么做”Skill是“你给模型一套他和同事都认可的标准作业流程”。所以Skills天然具备复用性、稳定性和可迭代性。这也是为什么我现在更倾向于把复杂任务的prompt沉淀成skills而不是保存在聊天记录里。技术细节上目前主流方案里SKILL.md文件头会有一段YAML格式的元信息声明这个skill的name和description。模型就是靠description来判断“什么情况下该调用这个技能包”所以这段description的文字质量直接决定了技能包会不会被正确触发。核心提示description里一定要写清楚触发场景比如“当用户需要把数据转换为特定图表格式时”而不是写得过于宽泛。1.2 Skill与Agent能力模块和调度主体的协作关系Skill和Agent的区别我见过最准确的说法是Agent是那个负责思考、调度、决策的“大脑”Skill是它手边工具箱里的“标准化组件”。Agent决定什么时候拿什么工具Skill负责把拿出来的活干好。具体到架构上一个Agent通常包含模型上下文窗口、工具调用能力、记忆系统、规划循环等等而Skills是Agent可以主动加载的一种特殊“工具”。它不是一个独立运行的程序而是给Agent提供了一套“遇到此类问题怎么办”的程序化指导。所以你可以把多个Skills装进一个Agent里让同一个模型在不同任务间切换不同的专业技能而不用为每个场景单独部署一个Agent实例。从开发角度看这意味着Skills的设计必须“向下兼容”不同的Agent框架。有的技能包在Claude Code里能用放Codex里可能因为目录约定不同就加载不了。所以做agent-skills时要特别注意跨框架兼容性问题后面我会细讲。1.3 Harness与Agent运行环境与智能体的边界热词里频繁出现“harness和agent区别”这个问题我在早期特别懵圈。Harness直译叫“马具”在Agent体系里指的是整个运行容器负责接收模型推理结果、调用外部工具、管理上下文窗口、处理错误重试、维护执行循环的那套框架层。Agent本身更像一个策略实体——它决定下一步该做什么而Harness负责实现这个决定去执行代码、去调API、去读取文件、把结果塞回上下文。Skills在Harness体系里属于一种按照约定格式提供特殊指令和脚本资源的扩展机制。我举个例子Claude Code的Harness会扫描项目里的.claude/skills/目录把每个子目录中的SKILL.md加载为可用的技能说明。真正执行时Harness根据模型返回的调用意图把对应skill的脚本跑起来再把输出交给模型继续推理。这个流程里Agent(模型)是在想Harness是在做Skill是在指导怎么做。三者分工明确理解这个边界后你排查问题会快很多——比如某个skill没生效可能是Harness扫描路径不对而不是Agent不聪明。1.4 Skill与Tool组织好的流程vs底层的原子操作再补一个很容易混淆的点。Tool是Agent可以调用的外部函数比如“执行Python代码”“读取文件”“搜索网页”它是原子操作一次调用干一件事。Skill则是把这些原子操作组合成一整套工作流还附带判断逻辑和检查标准。比如“图片生成skills安装包”这个热词如果做成Tool可能就是单个“调用绘图模型接口”的函数。但做成Skill时你会发现一个完整的图片生成技能包会包含需求分析、参数整理、prompt优化、质量检查、返工策略这么多个环节每一步都可能要调用好几种Tool。Skill是更高层级的封装Tool是它的积木。所以从易用性角度给Agent装一个成熟的Skill远比暴露一堆零散的Tool给Agent自由发挥要可靠。2. 为什么Skills突然火爆Agent从“能聊”到“能干”的关键一跃光看热词列表你会发现“pi agent”、“hermes agent”、“claude code skills”、“codex skills”这些搜索词密集出现背后其实有一个共性需求大家发现模型越来越聪明但投产使用时依然不够听话、不够稳定。Skills恰恰是现阶段解决这个问题最务实的方式。2.1 结构化的专家经验弥补模型的随机性大模型的输出天然带有随机性同一个问题你问十遍可能得到十种不同风格的答案。做Agent应用时这种随机性是致命的——你没法保证生产环境里每次生成的前端组件都遵守同一个设计规范。Skills的作用就是把这些规范用流程示例检查清单的形式硬性嵌入工作流把Agent的发挥空间限制在可控范围内。拿我现在常用的一个agent-skills项目举例。这个技能包里有一个“前端开发skills”它描述了一套标准流程先读设计稿提取色彩变量生成TypeScript组件骨架按项目规范写CSS最后跑一次lint。这个流程看起来简单但它把之前需要在一个很长的prompt里反复强调的东西整个固化成了可执行步骤。我实测下来模型按这套流程走产出的组件代码风格统一度提升非常明显基本告别了“每次都要改命名规范”的尴尬。2.2 规模化复用一次沉淀处处受益Skills还有一个被人低估的价值——知识复用。公司里可能有个老前端他清楚怎么写组件性能最好但要是每次写代码都要召唤他指导模型显然不现实。现在可以把他的经验写成Skills任何同事的Agent都能加载这个技能包自动按老专家的思路工作。这种能力沉淀和分发的成本远比训练一个微调模型低得多。社区里很火的Superpower Skills项目就是这种思路的开源实践。它整理了一大堆可安装的技能包从结构图生成到LaTeX排版、从逆向分析到图片生成用户装完之后Agent就能在对应场景下按一套更专业的流程执行。这个项目能在GitHub上快速获得关注说明大家已经意识到闭门调prompt的效率太低了直接拿一个结构良好的技能包来用是当前提升Agent实用性最直接的手段。2.3 生态分化各家Harness的Skills标准正在争夺开发者心智热词里“claude code skills 安装”和“codex skills”同时出现这反映了一个现状目前没有一个统一的skills标准而是各家的Harness各搞一套。Claude Code用的是.claude/skills/目录Codex有它自己的propmts和AGENTS.md约定Superpower走的是独立插件管理工具还有Pi Agent、Hermes Agent在尝试桌面端的能力集成。这个格局有点像当年浏览器插件标准的混战期对早期开发者来说是机会也是挑战。我的建议是先别急着站队尽量选择那些逻辑上通用的技能格式来编写和复用。比如把技能的核心逻辑写在独立的Markdown和脚本目录里再做一层薄薄的外壳去适配不同Harness。这样就算以后某个框架占主导了你的技能资产也不会被锁死。3. 主流Skills生态盘点哪些工具值得装差异在哪里热词里反复出现的几个名字我基本都折腾过这里按我的实际体验做个横向说明。表格放前面具体差异和适用场景放在后面细讲。3.1 各平台Skills机制对比速查平台Skills存放位置触发方式格式要求适合人群Claude Code.claude/skills/skill-name/SKILL.md模型根据任务描述自动匹配或命令强制调用YAML frontmatter Markdown正文 可选脚本/资源Claude Code用户喜欢全功能IDE式Agent工作流OpenAI Codex项目级AGENTS.md、prompts目录等基于项目说明和prompt文件自动加载特定目录结构和说明文档经常在GitHub仓库里跑自动化任务的开发者Superpower Skills通过CLI管理的技能包仓库安装后注入到兼容的Agent环境里自带格式安装脚本处理目录映射想开箱即用一大批高质量技能包的追求效率型用户Pi Agent / Hermes Agent平台专属目录支持导入外部技能包桌面端交互技能面板手动/自动触发各家文档约定总体兼容Markdown脚本风格喜欢桌面端Agent产品、想要可视化配置的玩家3.2 Claude Code Skills目前最成熟的技能开发范式Claude Code的skills机制是目前生态里我觉得最规范的一套。每个技能是.claude/skills/下的一个独立目录目录名即技能名里面必须有SKILL.md可以附带脚本、模板、参考文档等。SKILL.md的YAML frontmatter至少要包含name和description两块。description是模型判断是否触发该技能的关键所以要写清楚这个技能“解决什么问题、在什么场景用、用到什么输入”。正文部分可以分三块工作流程分步骤描述、检查清单完成标准、示例典型输入输出。我实际开发时的一个感受是Claude Code对skill脚本是有执行权限管理的你可以让它调用Python、Node甚至Shell。这就要求你写技能的时候必须考虑异常处理和依赖安装不能假设目标环境里什么都有。推荐做法是技能脚本入口写成bash里面先做环境检查缺什么依赖就自动装什么保证首次使用也能顺畅跑通。3.3 Codex Skills面向仓库级自动化任务的另一种思路Codex这边热词里“codex论文skills推荐”和“codex开发必备的skills”都很有代表性。Codex的应用场景更偏向“在代码仓库里自动改代码、跑测试、修issue”所以它的skills设计会更紧密贴着项目管理文件走。AGENTS.md就是给Codex看的一份项目说明书里面可以写明项目结构、命令规范、代码风格。在Codex环境里开发skills更多是把自己常用的“工作方法”写成可复用的说明文档放进项目约定目录。好处是技能跟仓库绑定换人接管项目时Codex还是能按同样的说明去操作。缺点是技能的可移植性不如Claude Code那种自包含目录形式。我建议如果你主要在GitHub仓库里跑自动化可以优先研究Codex这套如果更看重通用技能包的积累那还是以文件目录型skills为主。3.4 Superpower、Pi Agent、Hermes等第三方生态的思路Superpower Skills最近热度特别高因为它主打“超级技能包”装完就有各种现成的能力。和官方Harness自带的技能机制不同Superpower更像一个技能市场的角色你通过CLI搜索、安装社区维护的技能包它会自动映射到不同Agent环境的目录里。我实际体验下来它对“零基础想快速给Agent加技能”的用户非常友好但这也就意味着技能包的质量参差不齐。有些包写得挺敷衍只是把一段普通prompt包装一下真正优质的包往往带有充分的脚本资源、错误处理和示例数据。Pi Agent和Hermes Agent属于比较新的桌面端Agent产品它们把skills跟图形界面结合得更紧密能通过面板启停技能、查看技能运行日志。这类产品适合不喜欢命令行的人但从开发深度看目前还没达到Claude Code那种开放度。如果你只是想把Agent运用在日常办公场景里可以关注一下这些桌面端方案如果你想精研Agent开发那还是把精力放在主流的文件型技能机制上。4. Skills开发实战从零手写一个LaTeX排版技能包热词里有个“怎么做一个latex排版skills”这个需求特别典型我就用它当例子带你把整个开发流程走一遍。LaTeX排版的任务非常适合练手因为流程固定、检查标准明确、而且光靠prompt很难让模型保持稳定输出。4.1 技能目录结构与SKILL.md设计先规划目录结构。按Claude Code的约定技能包目录长这样latex-formatter/ ├── SKILL.md ├── scripts/ │ ├── compile_check.py │ └── fix_common_errors.py └── templates/ └── paper_template.texSKILL.md的开头是frontmatter用来描述技能的基本信息和触发判断依据。实际编写时我会把YAML里的description写得特别具体用户要求排版、要求LaTeX、要求论文格式、要求生成PDF时这个技能都算匹配。正文部分要包括工作流程、检查清单和调用提示。核心原则是这个文件不是给人看的说明书而是给模型看的“如何用这个技能干活的指引”所以描述要非常细致覆盖各种情况的应对策略。4.2 Skill核心参数与触发描述策略开发一个技能时最关键的决策就是description怎么措辞。太宽泛模型可能在不该触发的时候触发太狭窄模型又会无视它。以LaTeX技能为例我把description设计成两层逻辑第一层说清楚覆盖范围“结构化排版、参考文献格式化、图表环境构建、编译错误修复”。第二层写明硬性触发条件“当用户请求任何LaTeX相关任务或需要从Markdown/纯文本转为排版成品时”。我还习惯在description里留几个典型用户表述示例这能显著提高匹配准确率。比如用户说“帮我把这篇文章排版成能投期刊的样子”模型看到这个句子后台就会把这个技能包的匹配分数拉高。4.3 编写技能脚本编译检查与自动修复光有SKILL.md还不够一个真正的技能包要有可执行的脚本。LaTeX技能里我放了两个Python脚本。第一个compile_check.py负责用latexmk或xelatex编译.tex文件同时捕获日志中的错误和警告把编译过程可视化给模型看。这里面有个关键的实操要点LaTeX编译器的报错信息往往很绕比如“Missing $ inserted”这种模型直接看原始日志常常一头雾水所以我让脚本把错误信息翻译成人话“第20行附近数学公式缺少美元符号包裹”。第二个脚本fix_common_errors.py内置了一批常见错误的自动修复规则。比如检测到中文字符被塞进了数学环境就自动建议把文本切到\text{}里检测到表格列数不匹配就自动数一数每行的符号数量。这些规则看着简单但都是被真实编译错误磨出来的非常实用。4.4 实际调用流程与调优记录技能开发好以后在Claude Code里调用时模型会自动读取SKILL.md然后按我描述的工作流程执行。实测一次典型调用是这样的用户给出原始文稿说明“排版成IEEE会议论文格式”。模型扫描SKILL.md判定该启动latex-formatter技能。模型调出templates里的模板把原始内容填入骨架。模型运行compile_check.py脚本发现3个编译警告。模型逐一分析警报对其中2个直接修复剩余1个返回用户确认。确认后再次编译生成PDF交给用户。这个流程听起来平平无奇但如果没有技能包约束模型很可能在第一步就直接给你一个“看起来像LaTeX”但实际上编译不过的文档。技能的价值就是把“能编译、格式对”这种标准从prompt的主观期望变成了脚本的客观检查。4.5 开发注意事项与适配技巧做技能包时有几个细节特别值得提醒脚本在执行时的工作目录不一定在技能包目录内所以脚本开头要做路径定位用相对路径补齐。这一点我一开始吃过亏脚本在测试环境正常换了个项目目录就崩了。不要把要求全写在正文里尽量把关键约束放到脚本里做硬校验。文字要求模型可以“选择性忽略”脚本报错模型就不得不处理。技能包的banner不要加太花哨的内容保持精简、结构化方便模型快速理解一套标准流程。可以给技能包加一个tests/目录放几个最简单的测试用例这样每次修改完技能至少能确认脚本没坏。5. Skills的评估与测评怎样判断一个技能包值不值得留热词里直接出现了“skills怎么测评”说明大家都攒了一堆技能包但不知道哪些是“神器”哪些是“prompt套壳”。用我的话说测评一个skills好坏不能只看演示效果要看它能不能在真实多变的任务里稳定发挥。5.1 建立技能评估矩阵与测试样例集我自己的习惯是每要评估一个技能包就建一个小型评测集。比如针对图片生成技能准备10个不同类型的需求产品图、插画、照片级风景、3D图标等等。针对代码类技能准备5个不同的项目场景有简单的骨架生成也有复杂的遗留代码修改。固定输入之后就看输出质量、耗时、稳定性这三大指标。评估差别时最好设置一个对照组。比如同一个任务纯prompt跑一轮skill加持跑一轮看两者差异有多大。如果差异很小那这个skill的价值就存疑如果skill明显更稳、更贴合需求那才值得留。这个逻辑其实跟agent evals是一回事——只不过evals更偏整体技能测评更偏单项能力。5.2 常见测评指标完成率、稳定性、token消耗建模时我会用下面几个量化指标来打评分数简单可落地指标测量方法评价标准任务完成率同一个测试集跑多次统计成功完成的比例低于60%的pass需要优化或删除输出一致性多次生成的输出在结构、风格上的相似度结构越稳定越好说明技能约束有效token消耗记录技能调用总消耗的输入输出token相比纯prompt有明显增加则要检查是否过度冗长错误恢复能力故意制造异常输入观察技能能否自我修复能自动纠错是加分项死循环是减分项这里我特别提醒一个坑很多技能包的“演示成功率”很好看是因为它自己内置了一套固定的示例输入。你换一个真实场景的真实文件它可能马上就破功。这就是所谓的“过拟合”测试集。所以评估时要尽量用自己的真实业务数据来测不要只跑官方DEMO。5.3 实际评估案例前端开发skills的快速验收我最近评估过一个前端开发相关技能包按上面这套流程前后跑了半天。初始阶段它表现很惊艳能按照设计稿生成完整页面。但当我输入一个带特殊网格布局的设计稿时它产出的样式完全偏离了设计规范这说明它的规则没有覆盖到这种复杂情况。我据此打出了“可用但不成熟”的评价建议团队暂时别全量依赖。这种评估过程也让我意识到一个好的技能包应该是“内置了大量的边缘情况处理规则”的。评估技能时别只看它常规任务多顺更要看它“遇到不常见的输入时是优雅降级还是彻底摆烂”。这个判断标准非常实用。6. 常见问题与排查技巧实录6.1 错误“Agent execution terminated due to error”的处理思路这个错误信息在热词里反复出现也是很多Agent开发新手最头疼的。它本质上就是Agent在运行过程中抛了未捕获异常被Harness终止了。常见诱因有三种技能脚本自身崩溃比如Python脚本缺少某个依赖、路径不存在、文件是空的。排查方法很简单单独在终端里跑一下对应脚本看报错信息。模型输出被技能脚本截断当技能脚本涉及大量输出或者模型进入了很长的推理循环Harness可能因上下文超限而终止执行。这个最好通过缩短输出、增加流式处理来解决。权限和系统调用受限技能脚本尝试访问无权限目录或调用被禁止的命令也会触发终止。处理方式是检查技能包里的脚本权限尽量用相对路径操作。6.2 技能包不触发的定位方法技能装好了但Agent就是不调用这是大家反馈最多的“玄学”问题。按我排查经验90%的锅都在description写得不够好。你想想模型在决定调用哪个技能时就是你给的那段描述和用户任务文本在语义层面的匹配过程。如果描述里写了“当用户要求写代码时使用”但用户说的是“帮我实现一个登录功能”模型不一定能把这俩联系起来。改进方法很直接把描述写得更贴近真实用户的表达习惯多列几个同义说法。比如在描述里写上“实现功能、写一个组件、添加页面、编程、开发”等等变体。另外检查一下技能目录的路径对不对不同框架的扫描目录约定完全不同最容易犯这个错。6.3 技能冲突、环境依赖和版本管理装了多个技能包之后技能之间可能互相“抢活”。比如同时存在“前端备案”——一个叫“前端组件技能”另一个叫“页面构建技能”任务相似描述重叠模型就可能随机选一个。解决办法是合并同类项或者在各自描述中明确各自的边界比如“本技能专用于Table组件不处理页面整体布局”。环境依赖问题也很常见。技能包里的脚本用到了某个Python库但目标环境没有装。我的做法是在技能脚本的开头增加一段自动安装逻辑把声明和安装做成一体。但这会带来一个新的安全隐患——你安装了一个未知来源的技能包它可能在悄悄装些别的东西。所以我建议社区下载的技能包用之前先扫一眼脚本内容确认每一行都在干什么尤其是那些有curl、wget、pip install操作的技能包一定要谨慎。版本管理上我自己会为技能包目录单独建一个git仓库每次修改技能都打tag。这样一旦新版本表现不稳定可以回滚到上一个稳定版非常方便。Agent开发本来就充满不确定性技能包版本的回滚能力就是最后的兜底保险。6.4 agent安全和逆向技能的谨慎使用热词里还有“ai逆向skills”和“agent安全”顺手提一下。逆向类技能确实存在而且技能包生态越繁荣安全问题就越突出。我可以明确一个原则如果你不是在做合规的授权测试尽量不要加载逆向破解、绕过限制类的技能包。这既是合规问题也可能给你的开发环境引入恶意依赖。从我自己的安全习惯来说装技能包之前我会做三件事看作者历史记录、看脚本源码关键字有没有可疑的网络请求和系统调用、放在隔离环境里先跑一遍。Agent技能的“供应链安全”问题目前还没有完全被重视但这迟早会变成一个大问题早做防护没坏处。技能包被广泛下载就意味着它有巨大的注入风险。最后再分享一个小技巧Skills这种东西实践下来最容易踩的坑就是“贪多求全”。社区里有几千个技能包不代表你都要装。真正的Agent开发高手往往是自己写三五个贴合自己工作流的技能并持续打磨它们。我的建议是先找一个你最重复、最耗时的任务比如日报生成、代码审查、论文排版、结构化图表制作然后动手把它做成一个最小可用的技能包。等你体会到“模型按你的流程稳定工作”的感觉之后再逐步扩展技能包库这时候你会越来越有数。我个人在实际操作中还有一个体会技能包不是一次性写好就完事了它应该跟着你的需求一起演进。每遇到一个新的边界情况就往SKILL.md里补一条规则或者往脚本里加一个检测逻辑。坚持一个月这个技能包会变得远超那些“只会干常规活”的社区包。用上面这整套方法和思路去检视任何agent-skills生态里的项目你就不会再被那些花哨的演示迷惑一眼就能看出它到底是金矿还是坑。