最近两个月我在Agent开发上花的时间比过去一年都多。倒不是因为模型本身变强了多少而是因为“skills”这个概念突然把整条开发链路盘活了。做Agent的同行应该都有同感模型推理能力再强没有一套清晰可复用的技能体系它也只能在通用对话里打转一落到具体项目就各种拉胯。GitHub上冒出来一堆superpower skills、Claude Code skills、Codex skills仓库Pi Agent桌面端也把“技能”做成了核心入口连数学建模比赛的同学都在问有没有好用的Codex skill。这篇文章就把我这段时间折腾agent skills的经验整理出来从概念拆解到安装使用从自己写一个skill到排坑避雷一次性讲清楚。1. Skills到底是什么为什么Agent突然离不开它1.1 先看懂Agent的工作方式模型不是万能的要理解skills先得说清楚Agent的工作循环。一个Agent本质上就是“模型出决策、工具去执行、结果再喂回来”的循环业内常说的ReAct模式Reason Act就是干这个的模型根据当前状态想一想然后调用工具、读取结果再继续想直到任务完成。这个循环里最容易出问题的环节不是模型的“想”而是“怎么把想法变成规范动作”。比如你让Claude Code写一份中文LaTeX论文模型确实知道LaTeX是什么但它不知道你的编译链是XeLaTeX、不知道参考文献要用biblatex还是bibtex、不知道学校模板里字号和页边距的硬性要求。你每次都在prompt里长篇大论地交代这些规则不仅费token而且模型状态稍微一飘就会漏掉关键约束。Skills就是来解决这个问题的。它把“在特定场景下应该怎么做”的完整方法从对话提示词里抽出来变成一份Agent可以稳定读取和执行的“操作手册”。GitHub上热度很高的pi agent、hermes agent这类项目核心思路都是给Agent预装一组这样的技能让它上岗前就“会干活”而不是等用户现场教。这里还要顺手澄清两个经常被问混的概念skill和agent的区别以及harness和agent的区别。Agent是干活的主体它负责理解任务、拆解步骤、调度工具Skill是Agent可以调用的“干法”相当于岗位说明书里的一节操作规范。而Harness是承载Agent运行的框架外壳负责管理上下文、工具注册、权限控制这些底层机制。你可以这样类比Agent是厨师Skill是菜谱Harness是厨房。厨师要靠菜谱才知道怎么做菜但必须在厨房里才能开火。1.2 Skill不是插件而是一套“操作手册”很多人第一次接触skills容易把它理解成传统软件里的“插件”——以为装上之后就多了一个功能按钮。实际上完全不是。一个skill的核心通常是一个名为SKILL.md的Markdown文件里面用结构化语言写清楚这个技能什么时候用、前置条件是什么、执行步骤是什么、如何验证结果是否正确。拿一个标准的latex排版skill举例它的文件头会长这样--- name: latex-report description: 使用XeLaTeX排版中文论文。适用于需要生成PDF格式论文、报告的场景。 --- ## 使用前提 - 系统已安装TeX Live或MacTeX - 需要编译的主文件为report.tex ## 执行步骤 1. 检查report.tex是否存在若不存在则终止 2. 运行 xelatex -interactionnonstopmode report.tex 3. 检查日志文件是否报错若有错误则根据报错修正 4. 重复编译两次确保参考文献和目录正确 5. 确认生成的PDF页数在预期范围内看到没有这就是一份给Agent看的“交接文档”。它不需要解释LaTeX是什么、为什么要用XeLaTeX它只需要告诉模型遇到这个场景按这几步走每一步可验证做完怎么检查。这种设计有三个显而易见的好处。第一是省token规则不再重复塞进对话里Agent按需读取Skill文件就行。第二是可控收敛了模型在执行过程中的自由发挥空间减少“跑偏”的概率。第三是可复用同一个Skill可以在不同项目、不同Agent之间迁移写一次到处用。2. 主流生态盘点有哪些Skills值得装怎么装2.1 Claude Code Skills起步早、生态最全目前Skills生态最成熟的当属Claude Code。原因很简单Claude Code是最早把skills做成正式功能的终端Agent工具之一社区沉淀了大量可直接下载的skills包安装路径也非常规整。以Claude Code Skills为例安装目录一般是你用户目录下的隐藏文件夹# 创建一个skill的标准目录结构 mkdir -p ~/.claude/skills/my-skill # 核心文件必须叫SKILL.md touch ~/.claude/skills/my-skill/SKILL.md社区里最出名的要数superpower skills大礼包它把大量常用技能打包成一个仓库cloning下来之后直接放进skills目录就能用。我实测过里面包含的代码审查、Git操作、文档生成等技能识别准确率确实不错。另外有个叫tibo的开发者分享过一套清理skills的方法核心思路就是“定期删掉一个月没被动用过的技能”避免技能目录越来越臃肿这个我后面详细说。安装第三方skills时我强烈建议你先看一眼仓库更新时间。那些两年没动的老旧仓库里面的skill文件往往还停留在早期格式和当前版本的Agent工具对不上装上去报错的概率非常高。2.2 Codex、OpenCode与Pi Agent的Skills玩法Claude Code在skill生态上跑得快但其他Agent工具也都在快速跟进。OpenAI的Codex提供了skills能力你可以把常用的开发流程代码审查规范、测试用例生成方法、Git提交信息格式写成skill文件Codex在执行任务时会自动识别并应用。安装逻辑和Claude Code大同小异基本都是把skill放到指定目录然后在Agent配置里声明启用。OpenCode作为开源Agent终端工具对skills的支持也很积极社区维护了不少实用的opencode skills源。Pi Agent把技能做成了桌面端入口界面上直接能看到已安装技能列表点开就是对应的操作面板对不熟悉命令行的新手友好很多。还有hermes agent它主打的是可编程执行skill的粒度更细适合做复杂任务流编排。我个人的实验结论是不同工具对skill格式的解析细节有差异比如frontmatter里必填字段、是否支持子目录引用等但核心逻辑是完全一致的——都是“SKILL.md文件 附加参考文件”的目录结构。所以你写好一份合格的SKILL.md迁移成本其实非常低。2.3 从哪找靠谱的Skills源现在找skills的地方不少但质量鱼龙混杂。我常用的几个来源来源类型特点GitHub官方仓库 / awesome-skills列表聚合索引覆盖面广更新快但质量参差各Agent工具的官方marketplace官方市场经过基础校验兼容性较好技术社区博客分享个人维护往往附带使用心得适合理解使用场景大厂开源项目内置skills实战验证经过真实业务场景打磨质量可靠判断一个skill是否值得装我有一套自己的标准。首先看更新频率三个月内有commit的优先其次看SKILL.md的写法真正好的skill会写清楚适用条件、边界和验证方式而不是含糊的“帮助用户完成任务”最后看引用量如果README里敢放其它项目的测试结果说明作者真的有在维护场景兼容性。3. 自己动手写一个Skill从需求到落地3.1 好Skill的三要素场景窄、步骤明、校验强很多初次写skill的人容易犯一个毛病想把一个skill写得“万能”。比如写一个“代码生成skill”什么语言都想覆盖结果模型读完之后根本不知道现在到底该干什么等于没写。我做了大半年skill开发总结下来好skill有三个硬性标准。第一场景要窄。一个skill最好只解决一类具体问题。“帮用户写Python代码”不是好场景“生成符合PEP8规范的Python数据处理脚本并完成单元测试”才是。场景越窄写法越具体模型执行越稳定。第二步骤要明。Skill里的每一步都应该是可执行的描述而不是泛泛的提醒。比如“整理好代码格式”这种表述就太模糊应该写成“在提交前运行black --check .若格式检查失败则先运行black .自动格式化”。第三校验要强。这是最容易被忽略的。一个好的skill要告诉模型“怎么判断自己做成功”了。没有校验环节的skillAgent做完就完事出了错也不会发现。以图片生成为例校验环节就是检查输出文件是否存在、文件大小是否大于0、图片分辨率是否符合预期。3.2 手把手写一个“图片生成”Skill这里我以“图片生成skill”为例带大家一步步写出来。这类skill在素材创作、海报制作场景非常常用也是热搜里问得比较多的方向。先看目录结构my-image-skill/ ├── SKILL.md └── references/ └── prompt-templates.md再看SKILL.md的内容--- name: image-generation description: 根据需求生成高质量图片。适用于海报制作、插画生成、产品配图等场景。 --- ## 适用条件 - 用户需要生成一张新图片 - 用户描述的图片风格、主题清晰可执行 ## 执行步骤 1. 解析用户需求提取图片主题、风格、尺寸、配色倾向 2. 在references/prompt-templates.md中选择合适的提示词模板 3. 参考模板和用户需求组装完整英文提示词 4. 调用图片生成工具如DALL-E、Stable Diffusion API提交任务 5. 检查返回结果确认图片下载成功后将图片路径返回给用户 6. 如果生成失败调整提示词中主体描述最多重试2次 ## 校验方式 - 生成的图片文件存在且字节数大于0 - 图片尺寸与用户要求一致 - 图片主体内容与用户主题匹配若明显不符需要重新生成关键点在于“提示词模板”这个引用文件。图片生成任务里提示词写得好不好直接决定结果质量。我把常用风格、构图方式、负面提示词这些沉淀在单独的模板文件里让Agent不需要每次重新“发明”提示词直接参考现成套路组装出图成功率会高很多。3.3 本地调试与评估Evals写完一个skill别急着拿去生产环境用先在本地跑一轮调试。调试的核心思路是准备几组典型的测试用例让Agent在受控环境里执行看输出是否符合预期。这个过程业内通常叫Evals也就是评估测试集。拿图片生成skill举例我会准备三组用例一组是“生成一张科技感海报主色调蓝色”一组是“生成一张产品配图产品是无线耳机”还有一组是模糊需求“生成一张好看的图”。前两组验证正常场景第三组验证边界情况——模糊需求应该触发技能里的“追问澄清”逻辑而不是硬着头皮生成。调试过程中最常遇到的一个报错就是agent execution terminated due to error。出现这个提示我第一反应是去看Skill文件的路径有没有对、依赖的工具是否在环境中正常注册。这次排查经历后面细讲。反正记住一个原则先检查环境再检查skill内容。八成以上“不生效”的问题都不是skill写错了而是环境没接上。4. 实战避坑我用了大半年Skills的教训4.1 装了Skills没生效问题出在哪Skills不生效是我在社区答疑时被问到最多的问题。归纳起来基本跳不出这四类原因。第一类目录结构不对。有些工具要求skill必须放在指定的skills根目录下且每个skill一个独立子目录子目录里必须有一个SKILL.md文件。你如果直接把多个个skill文件平铺在一个文件夹里Agent扫描时无法识别自然不生效。第二类命名问题。SKILL.md里frontmatter的name字段最好和目录名保持一致。我有一次把name写成“image-making”目录名却是“image-gen”结果Agent在能力匹配时经常找不到正确的skill。第三类frontmatter格式错误。description字段写得太长、YAML解析错误、字段缺失都会导致skill被静默跳过。这类错误之所以难排查是因为Agent不会给你报错只是看起来“没反应”。第四类权限问题。尤其是在Linux服务器上部署Agent时如果SKILL.md文件没有读权限Agent会发现文件但读不了。用chmod命令扫一遍权限这些问题一分钟就搞定。4.2 别让Skills变成“毒药”安全这一节我必须单独拎出来讲。Skills机制给Agent带来的能力提升是巨大的但同时也引入了一个新的攻击面恶意skills。什么样叫恶意skills我曾经在一个“热门skill源”里下载过一份清理工具类的skill乍一看SKILL.md写得很规范但仔细翻它的执行步骤里面藏了一个命令把当前目录下的所有文件打包上传到某个远程服务器。这种命令人眼扫一遍可能发现不了但一旦Agent执行起来数据泄露就是分分钟的事。所以我对第三方skills的态度是信任但验证。安装前必须做两件事。第一通读SKILL.md全文重点看命令部分有没有看不懂的操作第二在隔离环境里先跑一遍确认行为完全可控再进入正式环境。另外给Agent配置权限时要遵循最小权限原则。Agent能跑的shell命令、能访问的文件目录、能调用的API都按需开放。不要因为“懒”就给Agent开一个全权账号那是给未来埋雷。4.3 不是越多越好我的推荐清单与清理方法Skills装多了你会发现一个反直觉的现象越多的skillsAgent的表现可能越差。因为Agent在决策时要读的“手册”变多了反而不知道该用哪一个。而且目录里堆了几十个skill之后扫描和匹配的时间也会变长。我现在常用的skills不超过十五个。这里分享一份个人推荐清单只列我实测下来高频且稳定的技能名称适用场景备注git-workflowGit提交流程、分支管理写规范git message非常有用code-review代码审查与规范检查能自动生成审查意见清单latex-report中文论文/报告排版解决XeLaTeX编译链问题image-generation图片生成与提示词组装我文章配图全靠它>