Agent开发新范式：全面拆解Skills的概念、安装与实战技巧

1. 为什么Skills突然成了Agent开发圈的高频词最近无论在哪个Agent交流群还是技术社区你都会发现Skills出现的频率高得吓人。从Claude Code、Codex到各种新冒出来的Agent框架大家讨论的话题从今天又调通了哪个API变成了这个Skills怎么装那个Skills好不好用。我自己的感觉是这轮Agent开发的范式正在经历一次明显的转向而Skills恰好站在了这次转向的中心。先说说最核心的观察。过去一年里大家玩Agent的方式基本是写System Prompt、堆上下文、不断调优few-shot示例。这种方式最大的问题是每换一个项目所有积累全部作废每换一个Agent框架心智模型又要重来一遍。而Skills这套设计带来的变化是——把一次性的提示词工程变成可复用的能力包。一个Skills装好之后你在Claude Code里能用在Codex里能装在别的兼容框架里也能跑就像给Agent塞进了一个独立的能力模块。另一个让人明显感受到变化的是skills这个词已经不再只是Anthropic文档里的一个技术概念而是变成了一个生态现象。你看这些热搜词里有superpower skills 安装codex好用的skills结构图skills图片生成skills安装包怎么做一个latex排版skills这说明大家已经不满足于知道这个概念而是真的想上手用、想自己造。有人甚至把Skills比作是Agent时代的插件市场——早期是浏览器插件后来是VS Code插件现在轮到了Agent Skills。更值得注意的是很多人在搜harness和agent区别skill和agent的区别这说明大家在使用这些工具时产生了明显的概念混淆。说实话这不能怪使用者因为不同的框架对同一套概念往往起了不同的名字有的叫Skill、有的叫Command、有的叫Capability底层逻辑相似但边界并不统一。所以才有了这篇文章的动机我想把Skills这摊事从头到尾捋一遍——它到底是什么怎么装怎么用怎么自己写一个以及有哪些坑我替你先踩过了。如果你现在是这么几类人这篇文章应该会对你有用想给Claude Code、Codex这类编码Agent装上各种实用Skills的开发者在纠结Agent、Harness、Skill这些概念边界想搞清楚架构选型的人想自己开发一个Skills不管是为了LaTeX排版、画结构图、还是更垂直的生产技能并发布给别人用的人以及单纯好奇Skills凭什么这么火的旁观者。我会尽量把每个环节都讲透从概念到实操从安装到调试最后还附上一些我实际使用中积累的避坑经验。2. Skill、Agent、Harness这三个概念先别混着用你如果去翻论坛会发现一大批求助帖其实都是概念没对齐导致的。所以我想先花一整节把几个基础概念捋清楚。这不是学院派较真而是因为你如果没搞懂它们各自的职责边界后面做架构设计、写Skills、排查问题的时候会非常痛苦。2.1 三者各自的职责边界先给一个最朴素的定义Agent负责决定做什么的主体。它接收用户的目标拆解任务调用不同的工具最后给用户交付结果。你可以把它理解成一个大模型驱动的大脑。HarnessAgent运行时的外壳或脚手架。它负责模型的循环调度、工具调用的分发、上下文的组织、指令的执行边界。通俗地说Harness决定了Agent怎么活着——用什么规则跑、每轮循环能调用什么、上下文满了怎么办。SkillAgent可以学会/加载的特定能力单元。一个Skill通常包含使用说明、参考知识和可执行的代码/脚本是Agent在某类具体任务上的业务能力。这三个概念对应到实际工程里就像是一个员工、工位、工具箱的关系Agent是员工负责判断该干什么Harness是工位规定了工作流程和能接触的资源边界Skill是放在手边的工具箱解决具体问题的时候打开对应的那个就好。2.2 用一张表和几个例子说清边界为了更直观我做了一个对比表维度AgentHarnessSkill核心职责决策与任务规划运行时调度与工具分发特定任务的知识与执行能力生命周期随着一次任务会话存在运行期间持续存在不想用时可以随时卸载可移植性相对固定绑定框架跨框架兼容性最好例子Claude Code里的默认主Agent驱动Claude Code运行的循环执行环境一个LaTeX排版Skills或结构图Skills类比员工工位/办公流程工具箱里的专用工具很多人混淆Skill和Agent其实是因为一些框架把Skill做得太重、看起来像个小Agent。比如说有些Agent框架允许你在一个Skill里嵌套多步决策和工具调用这时候Skill的行为确实已经接近Agent了。但有个关键差异仍然是清晰的Agent站在用户目标这一侧Skill站在任务能力这一侧。一个LaTeX排版Skills它不需要判断用户今天该干什么它只负责在用户决定要写论文、做简历、排报告的时候把排版这件事做得又快又好。2.3 为什么这个概念搞不清楚会直接影响开发我见过不止一个项目团队在讨论要不要把某个功能做成一个Skill的时候吵起来最后发现争论的本质是大家对于Skill和Agent的粒度理解不一致。把决策粒度放进了Skills里就会导致你根本没法复用——因为Skill一旦承担了决策职责它的输入输出就必然绑定到具体的业务场景换个项目就用不了了。反过来说把能力粒度全部塞进AgentSystem Prompt里又会让主流程变得臃肿不堪——每加一个能力都要动主Prompt上下文窗口的压力、调试的复杂度都会跟着涨。正确的做法是决策逻辑尽量留在Agent或Harness层业务能力放进Skills里。这样Agent保持轻量能力自由组合。你写一个结构图Skills既能配给Claude Code用也能在别的兼容框架里复用这就是把概念边界搞清楚的直接收益。3. 主流生态里的SkillsClaude Code、Codex、Pi Agent、Hermes一网打尽讲完概念接下来该上手了。目前市面上的Agent工具已经出现了一批成熟的Skills生态不同框架的实现思路和安装方式各有差异。这一节我会按工具逐个拆解覆盖最主流的几个让你能快速判断我的环境适合用哪个生态的Skills。3.1 Claude CodeSkills的成熟蓝本Claude Code是Anthropic推出的命令行编码Agent也是目前对Skills支持最完善的工具之一。它的Skills存放在~/.claude/skills/目录下每个Skill是一个独立目录里面包含一个核心的SKILL.md文件以及可选的脚本和资源文件。安装方式非常直接把skills目录克隆或复制到~/.claude/skills/下面重新启动Claude Code它就能通过SKILL.md里的描述自动识别和调用。如果想手动指定也可以直接在对话里说用xx skill来做这件事。社区里最受欢迎的Claude Code skills列表每隔几周就会换一波但我观察下来有几类长期稳定代码重构类比如agent legacy modernizer这种专门把老项目逐步现代化降低大规模迁移的心智负担文档排版类LaTeX排版、Markdown规范化、报告生成这类Skills特别适合写论文和做技术文档的人画图与图表类结构图Skills、架构图生成、流程图绘制这类通常结合SVG或Mermaid实现。3.2 CodexOpenAI生态的Skills路线OpenAI的Codex也在走类似路线。Codex Skills的安装方式和Claude Code略有不同通常是把skills放在Codex指定的配置目录下。安装完以后Codex会自动发现这些Skills并在合适的时候启用。社区里很多codex好用的skills推荐帖顶在榜首的多半是跟测试生成、代码审查、正则表达式生成相关的技能——这也符合OpenAI系工具在编程场景里更偏生成-验证循环的调性。有一点值得注意Codex对Skills的描述质量非常敏感。如果你的Skills描述写得很模糊Codex经常不会自动触发。我在后面讲自己写Skill的时候会专门说这个 description 的写法那几乎是决定一个Skill成败的最关键因素。3.3 Pi Agent桌面端的新玩家Pi Agent最近热度上升很快因为它有桌面端应用交互体验比纯命令行的Agent友好太多。很多人搜pi agent桌面端其实就是想试试在GUI环境里跑Agent和Skills。Pi Agent对Skills的抽象叫做能力插件安装时可以通过它的应用内市场搜索也可以手动导入本地目录。实测下来Pi Agent的优势是图形化的管理界面你能清楚地看到当前加载了哪些Skills、哪些没有被触发、触发次数是多少。这个对想搞清楚Skill到底有没有被调用的新手来说非常实用。3.4 Hermes Agent与Agentscope开源框架里的参考实现如果你想从框架层面理解Skills的底层实现Hermes Agent是个挺好的参考项目。它完全开源代码里可以清晰地看到Skills是如何被解析进System Prompt的、Skill目录里的文件结构是什么、Skill执行时的隔离边界在哪。对想二次开发或自研Agent的人来说读一遍Hermes的skills相关源码比看文档有用得多。另外一个值得注意的是Agentscope它里头有个skills demo把多Agent协作和Skill组合的用法演示得非常明白。它特别适合做多个Skill按流程组合的场景——比如先用数据分析Skill处理数据再用结构图Skill把结果画出来。3.5 Superpower Skills社区热度最高的Skill合集我不想用太多篇幅讲某一个具体资料包但superpower skills确实是搜索热度极高的一个词。它本质上是一个社区整理的Skills集合把很多常用能力打包成了一个仓库用户可以一键安装多组Skills。实用性上我建议不要全家桶式安装。装一堆用不上的Skills反而会让Agent的调用决策变慢、变混乱——因为每次触发判断都要把所有Skills的description过一遍Skills越多误触发概率也越高。最好的做法是装三五个你自己真实高频使用的用一阵子觉得不够再加。工具/生态Skills存放位置安装方式特点Claude Code~/.claude/skills/复制目录即可生态最成熟、文档全Codex配置目录指定CLI命令或手动放置对description质量敏感Pi Agent应用内管理市场安装或导入目录桌面端可视化Hermes Agent项目内指定源码配置适合学习底层实现Agentscope配置加载框架内注册多Agent组合能力强Superpower Skills覆盖上述生态仓库一键集成社区合集、品类全4. 动手写一个自己的Skills以LaTeX排版Skills为例前面讲的都是怎么消费别人的Skills但真正好玩的是自己写一个。这一节我以一个完整的LaTeX排版Skills为例把从目录结构到核心文件编写、再到测试和迭代的整个过程过一遍。4.1 Skill的基本目录结构与文件作用一个标准的Skills目录一般长这样latex-typesetting-skill/ ├── SKILL.md ├── scripts/ │ ├── compile_latex.py │ └── extract_metadata.py ├── references/ │ ├── template.tex │ └── package_map.md └── assets/ └── example_output.pdf各文件职责很清晰SKILL.mdSkills的身份证里面有YAML格式的元信息name、description以及给Agent看的完整使用说明。这是Agent决定要不要用这个Skill怎么用这个Skill的主要依据。scripts/可执行的脚本目录。Skill不是光靠文本知识就能办成所有事的真正的高价值能力往往体现为脚本——比如编译LaTeX、批量处理图片、生成SVG结构图。references/参考资料。注意这里不是给人类看的文档而是给LLM看的短时记忆补充——当Agent需要某类细节时它能在这个目录里找到对应参考。assets/输出物或模板资源。4.2 SKILL.md 的写法触发、步骤与知识分离先看一个精简但完整的SKILL.md例子只展示核心结构YAML头略作简化--- name: latex-typesetting description: 使用XeLaTeX/LaTeX进行文档排版。适用于用户需要生成PDF论文、简历、技术报告、学位论文等场景。当检测到用户提到排版、LaTeX、论文格式、简历PDF等关键词时自动触发。 --- # LaTeX排版助手 ## 前置条件 - 确保环境中已安装 TeX Live 或 MacTeX - 需要编译时优先使用 scripts/compile_latex.py 脚本 ## 工作流程 1. 从用户输入中提取排版意图论文/简历/报告和必要元信息 2. 查询 references/template.tex 选取最接近的模板 3. 填充正文内容调整样式参数 4. 调用 scripts/compile_latex.py 编译生成PDF 5. 将PDF路径返回给用户并附上编译日志的摘要 ## 注意事项 - 中文排版必须用 XeLaTeX并引入 ctex 宏包 - ……这里的核心有两点description 负责触发判断正文部分负责执行步骤。Anthropic的官方设计里SKILL.md应该只描述流程和边界不塞大段样例——比如不要把一份完整的LaTeX模板全文写进SKILL.md而是放在references里需要时按路径去读。这能显著减少上下文占用。4.3 为什么要单独写一个编译脚本很多人会问直接用自然语言告诉Agent怎么在终端编译不就行了实测下来不行。LaTeX编译有一个很头疼的特性——要跑两遍甚至三遍第一遍生成aux第二遍解析交叉引用第三遍确保目录稳定而且中途报错的位置信息非常反直觉。如果靠模型临场发挥经常在该重跑一遍的时候没跑或者一遇到警告就误判。所以我在Skill里加了一个compile_latex.py脚本固定执行xelatex - xelatex - 选择性再跑一遍的编译链在脚本层面就解决编译重数问题。同时捕获错误日志里的关键行过滤掉无用警告。这样Agent拿到手的编译结果永远是已确认稳定后再生成的PDF而不是它自己猜着跑的产物。$ python scripts/compile_latex.py main.tex [INFO] 第一次编译完成 [INFO] 检测到交叉引用变化重新编译 [INFO] 交叉引用已稳定 [INFO] 输出 PDF: build/main.pdf写这个脚本有一个额外好处Skill的调试和回归变得非常简单——换了新的模板、修改了中文字体配置只要跑一遍脚本看几个样例输入就能确认改动没有破坏原有功能完全不需要依赖Agent二次临场发挥。4.4 接一个图片生成Skills时的高频雷区顺着LaTeX这个案例第二个常见的需求是图片生成Skills。很多人以为图片生成Skills就是给Agent一个画图提示词模板但实际并非如此。你去看那些图片生成skills安装包下载量高的几乎都是通过程序化手段生成图片而不是调用外部图像生成模型。目前主流方案有几种SVG生成让Agent直接生成SVG代码再用渲染脚本转成PNG/SVG文件。适合画架构图、流程图、图标因为SVG是文本LLM生成它的掌控度很高。Mermaid中转Agent输出Mermaid语法通过mermaid-cli渲染成图。适合时序图、流程图、状态机图。需要提醒的是这依赖Node环境和Puppeteer安装时会遇到大量国内镜像问题最好提前配好。HTML转图片先让Agent生成一张HTML页面布局可控性最强然后用无头浏览器截图。适合生成社交媒体卡片、海报、简历预览这类页面型图片。我实测下来最稳的是SVG方案。原因很简单它对环境依赖最小、渲染结果确定性最高而且生成的图片可以被后续步骤继续编辑。缺点是LLM对复杂SVG路径的理解偶尔会出错所以脚本里最好加一步打开SVG检查尺寸和文本溢出的逻辑或者至少在输出前用正则做一次基础校验。因为这一类Skill和结构图Skills高度重叠所以如果你看到有人推荐结构图Skills大概率底层走的也是上面三种方案之一。4.5 测试Skill比你想的更讲究Skills写完之后测试不能只靠和Agent聊一句看看它调不调用。更靠谱的做法是直接看日志几乎所有Agent框架都会打印当前步骤调用了哪个SkillSkill用了哪些文件走了哪个分支。拿Claude Code举例用--verbose或--log开启详细日志之后你能看到系统在每一轮都评估了哪些Skills以及为什么选了这个Skill。如果它没触发你的新Skill多半是description写得不对。另一个更系统的方法是把Skill丢进Agent Evals里跑。搜索词里skills怎么测评对应的就是这个问题。做法很简单给Skill准备一组真实的高质量输入比如20份不同类型的排版要求预期输出是生成了合法PDF、内容完整性达90%以上然后批量跑一遍统计成功率。这个流程虽然不是必须做但如果你想发布一个给别人用的Skills强烈建议要做。我自己见过太多作者自认为很好用、别人一装就废的Skills几乎都栽在测试样本太少、太单一这同一个坑上。5. 安装和使用Skills的几个隐藏大坑前三节偏正面建设这一节我想换个角度聊聊那些我实际踩过、以及看群里人反复踩的坑。安装一个Skills看起来只是复制文件夹到指定目录但真正跑起来之后问题往往出在你想象不到的地方。5.1 别把提示词碎片当成Skills装进系统现在社区里冒出来很多所谓skills点开一看其实就是一段Markdown提示词。不是说提示词没用而是提示词与Skills的差别在于可执行性。一个真正的Skills应该有三个组成部分触发机制description、知识或指令markdown正文、执行能力脚本或命令。如果没有第三部分这个Skills本质上只是把System Prompt挪了个位置很难带来质的提升。所以我在安装别人写的Skills时会先检查目录里有没有scripts子目录、有没有实际可执行的逻辑。如果没有直接pass。下载图片生成skills安装包之类的东西时尤其要警惕——很多包装得很满实际效果就是把一堆提示词模板堆在一块。5.2 上下文空间的隐性占用每个Skill加载进Agent以后它的描述信息会占据一定的上下文窗口。装50个Skills哪怕每个只占几百个token加在一起也会挤占模型真正干活的空间。而且每次模型决定要不要调用Skill的时候都要把候选项扫一遍Skill数量越多判断越慢、误触发率越高。因此我个人的建议是Skills数量控制在10个以内而且每个Skill的SKILL.md不要冗长。如果你做的东西很复杂应该用摘要放在SKILL.md、细节放在references的方式把上下文消耗压低。5.3 脚本依赖是最大的不稳定因素Skills一旦涉及执行脚本就绕不开依赖问题。最常见的翻车现场是脚本依赖某个Node版本结果用户只有Python环境LaTeX排版Skills要求TeX Live但用户电脑上只装了TinyTeX用了Puppeteer相关脚本但本机没有安装对应浏览器内核。解决办法有两种按推荐程度排序一是尽量用系统自带能力 标准库实现比如Python的subprocess、pathlib这些少依赖第三方包二是实在要依赖就在Skills里附带一个setup.sh或者requirements.txt装Skill的时候顺手执行一遍把环境准备好。我自己发布Skills时一定会写清依赖而且尽量用Python标准库。5.4 安全问题Skills会执行任意代码这是目前讨论得最少、但最致命的问题。一个Skill的脚本本质上是让Agent在用户机器上执行任意代码。如果你从网上下载了一个来历不明的Skills又没有仔细审查里面的脚本等于把钥匙交出去了。我在自己机器上装第三方Skills之前固定做几步打开目录逐行看Scripts里的主力脚本搜索网络请求相关代码requests、urllib、socket、subprocess到外部命令等检查有没有读取环境变量、密钥文件的逻辑在不熟悉前先在一个临时目录或虚拟机里跑一遍。这一点不是劝退而是在Agent时代必须建立的习惯。agent安全这件事目前框架层面能做的隔离很有限真正防线还是在用户这一步。5.5 Agent记忆、Evals与Skills的组合用法最后一个容易被忽略的问题是如何把Skills和自己的使用习惯、项目背景结合起来。搜索词里有agent记忆和agent evals这两块恰恰是让Skills从能用变成好用的关键。Agent记忆决定了Skill能不能记住上次用户的偏好——比如你上次用LaTeX Skills时指定了字体和页边距那么下次触发时应该优先沿用。目前主流框架对这个的支持还不完全一致但你可以通过Skill脚本在自定义目录里记录一份配置文件来实现。Evals则是为了保证Skill在修改之后不退化——把一组历史任务固化成测试集每次改动后跑一遍成功率不降才能发布。这三者结合起来的完整工作流是用Agent记忆保存用户的格式偏好每次触发Skill时读取偏好、按需生成用一个固定任务集做Skill的回归测试确保升级不破坏老功能。这个铁三角是我现在所有自用Skills的标准配置。6. 面向Agent开发新手的两个认知聊完了实操层面的细节最后想再分享两个更元的认知。这两个认知不一定能帮你解决眼下的报错但能帮你在Agent开发这条路上少走很多弯路。第一个认知是Skills的爆发本质上是Agent行业从模型能力竞赛转向工程能力竞赛的信号。模型本身的智商差异正在逐步缩小真正的差距体现在的谁能为模型配好一套好用的工具。Skills就是这个工具装配层。这其实对开发者很友好——因为模型的训练和你没关系但Skills是你亲手写的其中的工程含金量实实在在掌握在你自己手里。第二个认知是现在花时间学习写Skills很可能复利非常明显。很多框架都有自己原生的一套东西一两年后可能就换了但Skills这套能力包的抽象正在被各生态事实统一。你现在掌握的知识在Claude Code能用在Codex能用在Pi Agent能用将来大概率还能迁移到更新的Agent平台上。这就像当年会写插件的人从Chrome迁移到VS Code再迁移到Figma能力本身是一直复用的。如果你正处在想学Agent开发但不知道从哪下手的阶段我个人建议的路径是先把官方文档里Skills相关章节读完再装几个社区热门Skills感受一下调用了Skill和没调用Skill的差距然后挑一个日常重复最多的小任务自己写一个极简Skill跑通全流程。这一步走完你对Agent开发的理解会有一次真正的质变远超看再多的教程。最后再分享一个小技巧在调试Skill的时候往往一个很小的日志开关就能让开发效率翻倍。无论你写的是Shell脚本还是Python都优先加一个--debug参数或者环境变量把Skill的执行过程打出来。这样装Skill的人遇到问题能自己排查你也省去了大量远程猜谜的时间。这个习惯我从第一个Skill开始保持到现在救过我无数次。