最近半年agent skills这个词在AI开发圈子里几乎刷了屏。你刷GitHub会看到一堆挂着skills字样的仓库看技术直播会听到主播在演示怎么装skill连不少IDE的Agent配置教程里都把skills单独列了一章。但你要是真问一句skills到底是什么跟agent、tool、harness有什么区别能一句话讲清楚的人其实不多。这篇东西就从一个实际搞Agent开发的人的角度把agent skills这件事彻底拆开。我会讲到它的文件形态、它在整套Agent体系里站在什么生态位、怎么从零手写一个能落地的skill拿LaTeX排版当例子、怎么装别人写好的skill、以及我在这个过程中踩过的坑和沉淀下来的一些设计原则。不管你是刚接触Agent的新手还是已经在写自己的skill仓库的老手这篇文章应该都能让你对技能封装这件事有一个更完整的判断。1. 拆开agent skills这个热词一个目录加一份说明书1.1 先从一个让我开窍的真实场景说起上个月有朋友拿着一个全新的Claude Code问我为什么别人演示里的Agent那么好用让它写文档就写文档、让它排版就排版、让它改代码风格就改代码风格我的Agent却像个只会复读提示词的憨憨我反问他你给Agent准备了什么他说我写了一大段system prompt把事情讲得很详细可它做出来还是不像样。问题就出在这。你试图用一段越来越长的提示词把整个领域知识全塞给Agent但上下文窗口是有限的指令一多重要的信息就被稀释了Agent反而不知道优先处理哪件事。Agent Skills这个设计要解决的恰恰就是这个痛点。它不是一个新出的神秘框架也不是某种编程语言而是一套把特定领域能力打包成可复用文件的规范。当Agent遇到对应场景时它才会加载这份手艺包而不是把所有知识无差别地塞进每一次对话。1.2 Skill的物理形态一个文件夹就是一门手艺我现在说的skill不是抽象概念它有非常具体的文件形态。一个标准的skill就是一个文件夹里面必须包含一个SKILL.md还可以按需放脚本、模板、参考文档、示例代码。比如我拿LaTeX排版举例目录长这样latex-doc-skill/ ├── SKILL.md ├── templates/ │ ├── article.tex │ └── beamer.tex ├── references/ │ ├── packages.md │ └── common-pitfalls.md └── examples/ └── project-report.texSKILL.md是整个skill的说明书它通常由两大部分组成开头一段YAML格式的元信息frontmatter以及正文的指令内容。元信息里最关键的是name和description两个字段。name是skill的标识description则写清楚这个skill擅长什么、在什么情况下该被调用——这个字段是Agent决定要不要加载这个skill的核心依据。正文部分则告诉Agent具体怎么做步骤是什么、有哪些约束、遇到边界情况怎么处理、可以参考哪些附带的模板和示例。一个skill可以很简单比如写Git提交信息这种几百字就能讲完的也可以很复杂比如从零生成一个符合某期刊格式的LaTeX论文需要带上一堆模板和引用资料。1.3 为什么说它是延迟加载的手艺包你可以把skill想象成老师傅的工具箱。工具箱不打开的时候不占你工作台任何空间只有当这单活儿确实需要扳手或电钻时师傅才去开对应的箱子。Agent的运行逻辑也类似平时跑任务并不会把所有已安装skill的全文都读进上下文而是先根据用户请求和已有skill的description做匹配。匹配上了才加载对应skill的完整内容。这个机制的名字叫渐进式披露progressive disclosure核心价值就是把宝贵的上下文窗口留给当前真正需要的信息。你想想如果装了几十个skill每个都有几K甚至几十K的指令每次对话全量加载上下文很快就会被无关内容占满Agent反而变笨了。而delay到需要时再加载技能再多也不会互相污染。这也是为什么现在各个Agent工具宁愿用文件夹SKILL.md这种朴素方案也不搞一套重量级的插件系统。2. Skills站在哪个生态位和Agent、Harness、Tool的关系2.1 Tool解决能不能做Skill解决知不知道怎么做很多人一上来就把skill跟tool搞混其实这是两个完全不同层面的东西。Tool工具是Agent可以直接调用的一段函数比如执行这段Python代码调用这个搜索API读写这个文件它解决的是能力边界的问题——Agent本身不能执行代码那给它一个execute_code工具它就能执行了。Skill解决的是另一个问题Agent就算手里有工具它不一定知道怎么把一件专业的事情做好。比如Agent能执行LaTeX编译器但它不知道一篇毕业论文的章节顺序应该怎么排、图表怎么编号、参考文献用什么格式。这些领域知识和操作规范恰恰就是skill要封装的内容。所以两者一点都不冲突skill里的指令经常会让Agent去调用某个tool两者是协作关系。2.2 Skill与Agent、Subagent的边界那skill和agent又是什么关系Agent是一个完整的、能感知环境、做出决策并执行动作的智能体它有自己的记忆、推理过程、行动循环。而skill只是agent可以使用的一本攻略它本身没有主动性不会自己去推理或行动。比较微妙的是subagent子代理。有些Agent框架支持在运行中创建一个子代理给它一个新的上下文窗口让它专职做一件事比如先用子代理做一轮代码审查再把结果交给主代理。子代理和skill的差别在于子代理是另开一个Agent实例有自己的上下文和运行循环skill则只是在当前Agent的上下文里追加一份指令。功能上两者有部分重叠差异主要体现在上下文隔离程度和编排复杂度上。实际项目中我个人的经验是涉及需要独立记忆、多步骤推理的复杂任务用子代理涉及把特定工作流和方法论固定下来的场景用skill。2.3 Harness到底是什么别再被绕晕热词里还有一个harness和agent区别这个词其实是这两年Agent工程化之后才频繁出现的。Harness直译是挽具、束缚装置在Agent语境里指的是包裹在Agent外面、负责连接模型、工具、上下文管理、执行循环的那一层运行时壳子。简单类比Agent是司机harness是方向盘、油门、仪表盘这套驾驶系统。司机agent负责判断怎么开但能不能控制车轮、能不能看到油量取决于harness提供了什么接口。常见的Agent框架里模型推理循环、工具调用协议、上下文窗口的管理、对环境的访问权限控制都属于harness范畴。Claude Code、Codex CLI这类工具之所以体验差异很大很多时候不是模型不一样而是harness层做得好不好。skill则更接近交给司机的一本操作手册它既不是司机也不是驾驶系统但好手册能让同样的司机和驾驶系统跑出完全不同的效果。2.4 一张表理清五个概念概念核心职责一句话类比会不会主动行动Agent感知、决策、执行的整体智能体司机会HarnessAgent运行的运行时壳层管上下文与工具调用方向盘、仪表盘不会Tool单个可执行功能扩展Agent能力边界工具箱里的扳手被动调用Skill领域知识工作流的打包指导Agent怎么做操作手册不主动靠描述触发Subagent独立上下文的新Agent实例承担子任务叫来帮忙的第二个司机会这个表不是教科书定义是我画给自己团队用的。理解这些区别的实用价值在于当你设计一个Agent项目时你得清楚当前缺的是哪一层。缺能力就补tool缺方法就写skill缺独立判断就开subagent缺整套执行环境就选harness。把问题归到错误的层级后面怎么调都别扭。3. 手写一个LaTeX排版Skills从需求到验证的完整链路3.1 为什么要拿LaTeX举例热词里怎么做一个latex排版skills被反复问到我就用这个场景做完整演示。选它有三个原因第一LaTeX排版规则明确、领域边界清晰很适合用来展示skill的设计思路第二很多人确实需要让Agent帮自己生成规范的LaTeX文档第三它能带出模板文件、参考资料、边界处理等多个skill设计要点。需求先定清楚这个skill不是教Agent怎么用LaTeX而是让Agent能按一份约定好的规范生成结构完整的LaTeX论文/报告。这两者有本质区别。前者是通用说明书后者是带强约束的工作流。3.2 设计skill的目录结构我的目录结构是上面展示过的那个latex-doc-skill。这里说几个设计上的取舍templates/放可复用的.tex骨架避免Agent每次从零写一堆重复样板。模板里用清晰的占位符标记需要替换的内容比如{{TITLE}}、{{AUTHOR}}。references/packages.md整理常用宏包的用途和坑。放进这个文件而不是直接写进SKILL.md正文是为了让正文保持精简。需要装宏包时Agent自然会去查这就是渐进式披露。references/common-pitfalls.md专门记录中文排版、图片路径、表格跨页这些高频坑。这个文件价值极高因为Agent本来最缺的就是实际操作中容易错在哪这类隐性经验。examples/放一个完整的示例文档作为Agent的参考实现。3.3 SKILL.md的写法要点先看一份精简版--- name: latex-doc description: 根据用户需求生成结构化LaTeX文档论文/报告/Beamer。当用户要求写学术论文、技术报告、毕业设计或需要ctex中文排版的文档时使用。 --- # LaTeX 文档生成指南 ## 适用场景 - 中文或英文学术论文、技术报告、Beamer演示文稿 - 需要ctex宏包进行中文排版 - 要求使用学校/期刊模板之外的通用规范排版 ## 工作流程 1. 确认文档类型article / report / beamer与目标语言。 2. 检查 references/packages.md确认本项目需要的宏包。 3. 从 templates/ 中选择对应模板复制到工作目录。 4. 依据 references/common-pitfalls.md 逐项规避已知问题。 5. 编译验证若编译失败按报错信息定位并修复。 ## 硬性约束 - 中文文档必须使用ctex系列宏包禁止用裸article配合中文字体方案。 - 图片统一放到 figures/ 目录用相对路径引用。 - 表格不跨页必要时使用 longtable 或调整排版。 - 参考文献统一用biblatex禁止手动编号。 ## 完成标准 - 文档能通过 xelatex 编译无 warning 级以上的错误。 - 目录、图表编号、引用关系正确。几个重点说一下。description字段我写得特别具体里面包含了什么时候该用的信号词用户提论文、报告、毕业设计、中文排版等意图时Agent才有较大概率触发这个skill。硬性约束这一节是整个skill的灵魂它是Agent遇到模糊决策时的裁决依据。比如没有这节Agent可能自己选一套宏包组合有了它Agent就知道中文必须走ctex是一条不可违背的规则。最后完成标准也很重要它给了Agent一个可验证的自检终点而不是干完就完。3.4 写完后怎么自测与迭代skill不是写完就能用的必须做一轮轮实测。我的自测流程是这样的第一步用一句很模糊的请求触发比如帮我写一篇关于图神经网络的简短的会议论文。训练有素的Agent应该自己去匹配这个skill而不是你手动告诉它请加载latex-doc。第二步检查生成结果里是否遵守了硬性约束。我会故意看细节有没有用ctex图片是不是相对路径参考文献是不是biblatex这一步能暴露出约束写得太软的问题。第三步故意制造边界情况看skill怎么兜底。比如让Agent生成一个内容跨度很大的综述文档检查它是否会利用模板、是否记住了分节规范。如果Agent在某个环节频繁跑偏我就回SKILL.md里补一条更明确的指令或参考文件再重测。第四步把编译失败的案例收集起来把失败原因写进common-pitfalls.md。这其实就是给skill做经验沉淀每多跑一轮skill就越接近一个真正懂行的老编辑。3.5 把skill发布出去自测通过之后把整个文件夹推到GitHub就是一个可分享的skill。仓库的README.md里建议把目录食用方式、适用场景、兼容的Agent工具写清楚。如果你愿意还可以在README里加个安装说明引导用户把目录拷贝到各自Agent的skills目录下。别小看这个动作——现在很多skill仓库火起来靠的就是README里那个一行命令安装而不是仓库本身的技术含量。4. 装别人的Skills几个主流工具的路径和坑4.1 Claude Code与Codex的skills目录先讲目录位置。Claude Code的skills默认放在用户级目录~/.claude/skills下每个skill是一个独立子文件夹如果你想针对某个项目生效就放到项目里的.claude/skills目录。Codex这边类似用户级目录通常是~/.codex/skills有些版本也支持项目级目录。CodeBuddy等兼容Claude Code生态的工具设计上也会复用类似目录结构。这里有个很容易迷惑的点到底该装用户级还是项目级我的建议是通用型技能写提交信息、做代码审查、整理README装用户级所有项目都能用领域特定技能针对某个前后端框架、某个期刊排版规范装项目级避免在无关项目里被误触发。目录选错了不会报错但会在实际使用时出现明明装了skill却不生效或者相关度不高的skill频繁乱入的体验问题。4.2 手动安装GitHub上的skills现在很多skill发布在GitHub上安装方式其实就是把仓库拷贝到对应的skills目录。以Claude Code为例# 把仓库克隆到临时目录 git clone https://github.com/yourname/github-skills.git /tmp/github-skills # 把skills目录下的技能复制到Claude Code的skills目录 cp -r /tmp/github-skills/skills/* ~/.claude/skills/ # 查看已安装的技能 claude --list-skills大多数repo会提供install.sh本质上也就是把对应目录同步过去。需要注意如果你改了skill内容后面再跑官方安装脚本可能会被覆盖所以我通常习惯把第三方skill复制过来后在本地仓库之外再维护一份自己的改动或者直接fork原仓库。4.3 superpower skills这类合集怎么处理superpower skills这类合集包是现在最火的skill资源之一它把几十个整理好的技能打成一个包一键安装。这类合集的价值在于开箱即用能让你快速感受各种skill带来的变化。但我的建议是不要把合集原封不动全量装进去——几十个skill全堆在目录里description互相覆盖的概率会显著增加反而影响匹配准确度。更务实的做法是先全量装一遍感受效果然后只保留你真正高频使用的几个其余删掉。等用熟了再去看这些合集仓库里的实现细节学习别人怎么写SKILL.md把好的写法吸收进你自己的技能里。合集是学习素材不是最终依赖。4.4 跨工具共用skills目录的实测关于codebuddy和claude code公用skills目录这个热点我的实测结论是多数情况下可以共用但要踩两个坑。第一个坑是格式兼容性。虽然大家普遍采用SKILL.md规范但不同工具对frontmatter字段的解析略有差异比如有些工具要求description必须是一段能被语义检索的完整句子而另一些工具支持全文检索。同一份skill在A工具里触发正常在B工具里可能触发率暴跌。第二个坑是配置路径。CodeBuddy和Claude Code都通过配置文件指定skills路径时如果两边的配置文件分别指向同一个目录确实能共用。但项目级配置和用户级配置混在一起时经常会因配置优先级不同导致加载错乱。如果你确实想跨工具共用我建议把skill仓库放到一个独立目录然后两边配置文件都指向它而不是分别拷贝一份。这样至少保证版本一致出问题只改一处。4.5 我踩过的三个安装坑第一个坑装完不生效。多半是目录层级错了——skill文件夹外面多套了一层目录导致识别不到SKILL.md。检查一下路径应该是skills/某个技能名/SKILL.md而不是skills/某个仓库名/某个技能名/SKILL.md。第二个坑描述太模糊导致不触发。很多skill作者会把description写得很宏大比如帮助用户完成各种任务这种描述等于没说Agent根本没法判断什么时候该加载它。要么你自己改description要么弃用这个skill。这其实也提醒了skill作者description直接决定skill的生死。第三个坑缓存导致的旧版本问题。有些工具会缓存技能元信息你更新了SKILL.md里的内容但工具还在用旧缓存。重启会话通常能解决极少数情况需要清缓存目录。不要一上来就怀疑是不是我改坏了先重启再排查。5. 把Skills做对设计原则、评估与安全边界5.1 description是触发器不是功能简介skill开发里最反直觉的一件事是description写得好不好比skill本身写得好不好更重要。因为Agent是通过一段自然语言描述来决定要不要加载一个skill的这段描述如果写得像产品简介Agent就很容易漏触发。它应该是一段用户可能会怎么说需求的信号词集合。举个例子。假设你写了一个处理性能问题的前端skill下面是三种写法差前端性能优化工具包含资源压缩、懒加载、缓存策略。中用于前端项目性能优化可诊断加载速度、减少打包体积。好当用户提到网页加载慢、首屏时间过长、打包体积大、Lighthouse分数低、图片压缩、懒加载、优化构建产物时使用。第三种写法给出了大量用户原话级别的信号词Agent匹配成功的概率会高很多。写description时要反复问自己用户会用什么样的词句提出这个需求把这些词句直接扔进去。5.2 单一职责把一门手艺拆干净我刚开始写skill时总想一个skill解决所有问题结果就是SKILL.md越写越长最终变得又臭又硬Agent加载后反而更无所适从。后来我学到的原则是单一职责一个skill只解决一个问题域。排版就是排版写commit message就是写commit message不要试图把它们合并。如果几个skill之间的边界确实有重叠正确的做法是让它们通过引用协作而不是内联合并。比如前端项目初始化这个skill里可以写一句若需要配置代码规范参考code-style-skill然后让Agent自行判断是否加载另一个skill。这样每个skill保持小而精组合起来却可以覆盖复杂场景。这个思路跟软件工程里的模块化其实是一回事高内聚、低耦合放到skill设计上同样成立。5.3 用Evals验证skill真实效果热词里反复出现agent evals说明大家已经意识到不能光靠感觉评价一个Agent或skill。我也把skill纳入了自己的评估体系。做法不复杂准备一组固定的测试任务比如10个LaTeX生成需求然后分别记录有skill和没skill两种情况下的输出质量从格式规范、编译通过率、内容结构三个维度打分。实测下来好的skill能把文档编译通过率从50%拉到90%以上这就是肉眼可见的提升。但也要警惕另一种情况有些skill看起来写了大量约束实际执行时Agent却把时间都花在遵守格式上忽略了内容质量。所以评估维度一定要包含内容层面的指标而不能只看技能规范是否被遵守。把评估结果记录下来定期回看skill才会越用越准。5.4 安全边界skill也是代码这是最容易被忽视的一点。skill的本质是可被Agent自动加载并执行的指令集合它完全有能力诱导Agent做出有风险的行为。比如一个恶意skill的description写得很具迷惑性被触发后会指示Agent读取用户目录下的配置文件并发送到某个地址这类风险在真实项目里完全可能发生。我现在的处理方式是有几条硬规矩的第一不安装来路不明的skill尤其是那些含可疑脚本或强烈要求联网传输数据的第二安装第三方skill后不直接使用先通读一遍SKILL.md重点看它有没有要求Agent做与描述无关的额外动作第三凡是涉及读取某类文件向某地址发送数据绕过某种检查的指令不管来源多权威一律警惕并从本地删除。把skill当作需要审阅的第三方代码来对待而不是当作普通文本这个习惯能帮你挡掉大多数安全问题。5.5 下一步skill市场和agent协作的可能性目前skill的生态还在快速进化。一方面各个工具都在完善skill的发现、安装、版本管理机制实际上就是在往应用市场的方向走另一方面更前沿的方向是让agent之间能共享和交换skill——我做了一份好用的技能我的agent可以把它教给你的agent这已经超出了传统插件分发的范畴。我对agent skills的判断是它会像当年的npm、pip一样逐渐沉淀出一套公共的约定和生态。未来Agent之间的竞争很大程度上会从谁的模型参数大转向谁手里积累了一套高质量的skills库。模型是通用引擎skill才是真正的领域资产。早点开始把自己的工作流整理成skill就是在做一笔越滚越大的复利投资。最后再分享一个我个人的体会如果你刚开始接触skills不用追求一下建造一个多么宏大的技能体系。找一个你每周都会重复做的任务比如写周报、生成项目release notes把它做成第一个skill。在做的过程中你会自然理解description怎么写、约束怎么定、模板怎么拆。第一个skill做顺了后面就会像搭积木一样越来越快。先跑起来比什么都重要。