1. Skills是什么以及它为什么不是更长的提示词1.1 我为什么突然开始认真整理agent skills前阵子给项目做一次例行重构发现整个agent项目里散落着十几个临时提示词今天加一段请你用Python计算明天补一句请按LaTeX格式输出。结果agent的表现时好时坏换一个任务描述方式输出格式就变了稍微改一下语境它又退回了通用大模型的默认行为。后来我把这些临时提示词整理成一个个独立的skills情况立刻不一样了。同样的操作稳定性和可复用性完全是两个级别。这次经历让我觉得很多刚接触agent开发的人对skills的理解可能还停留在skills就是写一段更长的提示词给AI看这个误区值得单独拿出来说说。这篇文章会围绕agent skills到底是什么、手写一个完整的skills要经过哪些步骤、主流agent框架里skills的存储和加载方式有何不同、以及如何筛选第三方skills这几个问题展开。适合刚入门agent开发、或已经在用Claude Code、Codex这类工具但不太熟悉skills机制的读者。1.2 从提示词到skills到底进化了什么拿日常工作中的SOP来类比比较好理解。你给一个新同事口头说一句帮我把报告排一下版他大概率会按自己的想法来但如果你甩给他一份《排版规范》手册里面写了字号、行距、标题层级、目录生成方式、遇到特殊情况怎么处理他每次产出的东西就能保持稳定。skills本质上就是给AI agent用的这套操作手册。普通的提示词只解决当前这一步怎么做。它没有固定的输入输出契约没有可落地的执行步骤也不会去调用额外的脚本或工具。而一个合格的skills至少包含这几层触发条件什么任务下该启用这个能力得有清晰的适用范围不能什么都接。执行步骤把任务拆成有序的流程每一步给到agent可执行的动作而不是一句模糊的请尽力完成。输入输出约定预期拿到什么格式的数据、最终产出什么格式的结果必须写清楚。外部依赖可能需要引用一些参考文档、脚本、配置文件这些也属于skills的一部分。边界与兜底什么情况下要停下来询问用户什么情况下使用备选方案。所以skills不是更长的提示词而是一份可版本管理、可复用、可组合的能力包。你可以把一份写好的skills从Claude Code迁移到其他支持类似规范的agent上就像把员工的SOP手册复印一份给另一个部门同事用底层方法完全一致。1.3 skill和agent的区别一个是被调用者一个是执行体很多人在刚开始接触这个概念的时候会把agent有skills和agent就是skills搞混。我个人的理解是agent是负责调度、记忆、决策、调用工具的完整智能体而skills是agent可以装载的一个个独立能力模块。举个例子agent本身就像一个全科医生它知道什么时候该看内科、什么时候该看外科而skills就是内科、外科、眼科这些专科诊疗方案。全科医生可以在接诊时根据症状调用不同科室的诊疗流程医生本身不会因为换了一家医院就失去分诊的能力但这些专科方案是可以独立更新、被不同医院共用的。一个agent通常要同时管理记忆、对话上下文、工具调用和执行流程这部分是它作为执行体的职责skills则更聚焦在某一个具体领域该怎么干活。agent负责决定用什么skills负责把这件事做对。所以每次有人问skill和agent哪个重要我的回答都是它们是两个维度的问题根本不该放在一起比较。1.4 skills与agent记忆两个容易混在一起的概念还有一个高频困惑是skills和agent记忆有什么区别。简单说记忆是agent对过去交互历史的保存和检索它告诉agent这个用户上次选了哪种方案skills则是能力设定它告诉agent处理某类任务时应该按什么标准步骤来。我在项目里会把记忆和skills彻底分开管理。记忆放在向量库或结构化存储里由agent运行时读写skills放在独立的目录里用文件和脚本固化。这样做的好处是skills可以跨项目复制、可以交给别人review、可以单独测试而记忆跟具体业务数据强绑定混在一起只会让代码越来越难维护。如果说agent是被调度的执行体记忆是它脑子里的工作记录那么skills就是它的工具箱。三者分离各司其职agent项目才能撑到一定规模而不烂掉。2. 手写一个Skills文件的完整过程拿LaTeX排版Skills练手2.1 需求拆解先给这个skill画出边界直接上手写skills之前最忌一上来就动笔写步骤而应该先想清楚这个skill的边界。以LaTeX排版skill为例——这个需求在论文写作、竞赛报告场景里特别常见我群里已经有三四个人问过怎么做一个latex排版skills了。我先拆需求触发场景用户给出一个Markdown或纯文本的文档结构希望得到规范的LaTeX源码。输入文档标题、章节层级、是否有表格、引用格式要求、中英文混排要求。输出一个可直接编译的.tex文件包含完整导言区和正文中文场景下需要指定合适的ctex或xeCJK方案。边界不负责具体内容的生成只负责排版骨架不处理复杂的自定义宏包因为那通常需要人工确认。这个边界很重要。如果不在skill里写明只负责排版骨架不负责内容创作agent很可能越界帮你把正文也扩写一遍产出的内容反而没办法直接用。2.2 目录结构不该只有一个markdown文件很多初学者以为skills就是一个文本文件这也是误区之一。拿我现在项目里实际在用的结构举例一个完整的skills一般长这样latex-format/ ├── SKILL.md ├── references/ │ ├── 中文学位论文模板.tex │ ├── 英文会议模板.tex │ └── 表格与插图规范.md └── scripts/ ├── check_latex.sh └── escape_special_chars.pySKILL.md是主描述文件agent优先读它来决定这个skill怎么用references放参考文档和模板scripts放可执行的工具脚本比如检查生成的TeX文件能否被常见编译器解析。不要把所有的东西都塞进一个SKILL.md。主描述文件最好是说明书而不是百科全书它负责告诉agent有哪些资源可以用、按什么顺序用具体细节放在references里按需读取这样能节省上下文窗口也让整个skill更容易维护。这个设计思路我是在看了不少开源skills之后才摸清楚的一开始我也习惯把所有细节都堆进一个文件结果每次调用都吃掉大量上下文还容易让agent抓不住重点。2.3 一个可以直接套用的SKILL.md实例下面这个是我实际在用的LaTeX排版skill简化版你可以直接抄去改--- name: latex-format description: 将Markdown或纯文本内容转换为规范的LaTeX源码。适用于学术论文、技术报告、竞赛文档等场景。 --- # LaTeX排版助手 ## 触发条件 - 用户要求生成LaTeX代码或将文本转换成LaTeX格式 - 用户明确提到论文、报告、竞赛文档排版需求 ## 输入 - 文档标题 - 文档类型article/report/book - 是否包含表格、图片、公式 - 中英文格式要求 ## 执行步骤 1. 检查用户提供的文档结构提取标题层级。 2. 在references/中寻找与用户场景最接近的模板文件。 3. 根据模板生成tex文件骨架 - 中文文档使用ctexart文档类 - 英文文档使用默认article字体设为Times New Roman兼容方案 4. 将正文内容逐段填入注意 - 特殊字符如 % # _ { } 需要转义 - 图片路径统一使用relative/path引用 - 表格使用tabular环境统一列宽 5. 运行scripts/escape_special_chars.py 检查转义问题。 6. 运行scripts/check_latex.sh 检查括号配对和begin/end配对。 ## 输出格式 返回一个完整的.tex文件源码并附使用说明包括使用的编译器xelatex/pdflatex和注意事项。 ## 注意事项 - 不要随意添加未在模板中出现过的宏包。 - 用户要求定制样式时先询问清楚再动手。 - 如果内容中包含复杂表格或公式布局先给出方案让用户确认再生成完代码。这段内容里的metadata部分name和description是给agent做匹配用的描述写得越具体触发越精准。步骤部分则要遵循一个原则让agent每一步都能产生一个可检查的中间结果而不是让它一口气做一个大黑盒操作。2.4 调试技巧如何避免执行到一半报错写skills的人大概率都见过类似agent execution terminated due to error.的报错。我第一次看到这个报错的时候以为是自己提示词写得有问题反复修改措辞都没用。后来排查才发现问题出在skill里引用了一个不存在的脚本路径agent按照步骤执行到第三步发现文件找不到整个流程直接终止。这个报错本质上不是提示词写错了而是skill的资源完整性出了问题。现在我的排查顺序已经固定成一套套路检查SKILL.md中引用的每一个references和scripts路径确认相对路径在skill目录内真实存在。检查scripts是否有执行权限如果涉及shell脚本先手动跑一遍确认退出码为0。检查步骤之间的依赖关系务必确保前一步的输出格式是下一步能直接读取的。在SKILL.md里加一条兜底如果执行过程中出现无法解决的错误应该向用户报告错误原因并停止而不是强行继续。还有一个很多人不知道的技巧给skill目录加一个tests/子目录放几个典型的输入输出用例。即使agent工具本身不运行测试你在调试阶段也可以手动模拟一次完整调用看看哪个步骤会断。这一步能帮你省下大量和报错搏斗的时间。3. 主流Agent框架里Skills的存放与加载方式对比3.1 Claude Code手动安装GitHub上Skills的方法Claude Code是目前把skills概念贯彻得比较彻底的工具之一。它会在项目目录里找.claude/skills/这样的目录结构每个子文件夹就是一类skill里面同样是一个SKILL.md加若干辅助文件。从GitHub上装一个第三方skill本质上就是把它克隆到对应目录然后在Claude Code里重新加载。实际手动安装的步骤大致是在GitHub上找到目标skills仓库通常是xxx-claude-skills这类名字。把仓库clone下来或者单独下载某个skill文件夹。放进项目的.claude/skills/或全局配置对应的skills目录。在Claude Code里重启会话或运行技能加载命令让新skill生效。听起来很简单但很多人会栽在执行权限上。GitHub上的skills经常带.sh脚本clone下来后这些脚本默认没有执行权限agent调用时就会报错。所以我在装完每个skill后的第一件事就是检查目录里的脚本是否有x权限。3.2 Codex与OpenCode文档化知识包路线OpenAI Codex这条线和Claude Code的skill机制就不太一样。它更依赖AGENTS.md这类项目级规范文件把说明文档放在固定位置agent在进入项目时自动读取然后按文档里定义的规则来执行任务。这种方式下你说的skills更像一套知识包强调的是让agent理解项目的背景和约束而不是给它一个可调用的函数。OpenCode也有类似的机制支持用户定义命令、agent规则、项目说明文档。我在OpenCode里更习惯把技能设计成一个个独立的命令输入一个路径或参数就能让agent按预设流程处理。这两种思路其实是互补的Claude式skills偏向流程编排把步骤固化下来Codex式偏向知识注入让agent读文档之后自己规划。如果你项目里既有完整流程又希望agent保留一定的自主性可以考虑混用但前提是你得清楚每个skill在哪一层生效。3.3 浏览器Agent类工具另一种skill形态说到Pi Agent、Hermes Agent这类最近比较活跃的开源agent它们的skill形态又不一样。这类agent主要工作场景是浏览器自动化所以它的skills往往是一组可复用的浏览器操作指令包比如打开某个页面、定位元素、点击按钮、提取数据这一整串动作可以被封装成一个skill下次遇到同类型网站时直接调用。和写LaTeX这种文档类skill相比浏览器操作类skills的调试难度更高因为页面结构经常变。我给这类agent写skills时会刻意把选择器定位和业务动作拆开放在两个文件里。页面改版了只需要更新选择器那一层不需要动整个业务逻辑。如果你不是特别清楚某个agent支持哪种skill格式先找一个官方sample拆开看看比自己摸索快得多。3.4 不能漏掉的Superpower Skills合集聊skills推荐很难绕过superpower skills这个项目。它的思路是把一套相对完整的工作方法论打包成一堆skills比如任务拆分、代码审查、技术方案设计每个技能都是单独的markdown文件组合起来用效果非常好。这个合集受欢迎的原因其实不在某个单独的skill写得多惊艳而是它的体系感很强它会引导agent先思考、再规划、再执行、最后反思整个流程符合高素质工程师做事的习惯。我在项目里借用过它的任务拆分skill改造后几乎成了我所有agent项目的标配。安装它通常是直接clone仓库到Claude Code对应的skills目录具体路径每个版本可能有差异以仓库README为准。需要注意这类合集更新频繁不建议直接修改原文件而是把自己定制的版本放到独立目录里方便以后合并上游更新。3.5 各框架skills对比一览框架/工具skills的主要形式启用方式适用场景Claude Code.claude/skills/目录中的SKILL.md 脚本文件放入目录后重启会话或加载完整流程编排、本地脚本调用CodexAGENTS.md等规范文档启动时自动读取项目级约束、知识注入OpenCode命令、规则、文档配置文件中注册轻量命令与自主规划结合Pi Agent / Hermes Agent浏览器操作指令包按工具说明导入网页自动化、数据采集Superpower Skills成套方法论文档clone到skills目录通用任务规划、代码工作流这里有个心得当你在不同框架之间切换时不要指望同一个skill文件能原样到处跑但它的设计思路完全可以迁移。重要的不是文件格式而是你在这个skill里沉淀的步骤、边界和输出规范。4. 日常收藏的Skills源以及筛选第三方Skills的避坑经验4.1 值得定期翻一翻的GitHub仓库类型找skills和找开源库不一样很难靠一个搜索词就命中所有好东西但有一些固定的矿脉值得定期去翻awesome系清单仓库搜awesome-claude-skills、awesome-ai-agents这类聚合仓库里面会按用途分类整理社区里比较成熟的skills。竞赛和论文相关的skills仓库数模竞赛场景尤其典型。每年比赛前我都会看到有人把常用的数学模型、论文排版规范、数据分析流程整理成一组skills比赛时让Codex直接调用。这种时效性强的skills仓库问题在于很快过时但拿来当灵感来源非常合适。特定垂直领域skills比如前端开发skills这类仓库会把一个前端任务从组件结构、样式方案到代码规范完整固化下来。如果你经常用agent生成前端代码这一类是刚需。我用一个本地目录专门收集这些仓库的链接并且给每个仓库打上标签流程型、知识型、工具型。这样找到新skill时先归类再决定要不要装进agent项目里。4.2 图像生成、设计类Skills值得装吗热词里有图片生成skills安装包和ai漫剧常用skills说明图像生成也是大家普遍关心的方向。图像生成类skills和排版类的本质差别在于图像生成的关键在提示词结构、参数调优和出图后的筛选逻辑。所以一份靠谱的图像生成skill通常会把提示词拆成主体、风格、构图、光影、负面提示词几个部分并规定一个先生成草稿供用户确认再出大图的工作流避免用户直接等待昂贵的多轮生成。这类skill我建议优先用社区里经过验证的版本而不是自己从头写。原因是图像生成的坑非常多比如中文字体乱码、长宽比触发生成模型上限、负面提示词和正面提示词冲突等等这些都是社区用真金白银的API费用试出来的经验自己重新踩一遍成本太高。4.3 装第三方Skills前必须检查的几件事第三方skills虽然能提升agent能力但也伴随风险。因为skill本质上是把一段指令和脚本交给agent执行所以必须谨慎。我给自己定了几条硬规矩分享出来供参考看脚本内容不只看描述。任何带.sh或.py的skill我都会先打开脚本通读一遍确认里面没有可疑的下载、上传环境变量等行为。这一步花不了几分钟但对agent安全至关重要。在隔离环境里试跑。新装的skill先在测试目录或沙箱环境里跑一次确认行为符合预期再放进正式项目。检查依赖引入方式。skill里如果写死了某个外部URL要警惕后续版本变更带来的供应链风险。优先选择不依赖外部动态内容、或者依赖内容可锁版本的skill。留意触发描述的覆盖范围。有些skill的description写得特别宽泛比如处理任何文档任务这会让agent在无关任务上也频繁调用既浪费时间又可能产生错误结果。发现这种情况我会手动收窄触发条件。这里展开说一下agent安全的问题。一个恶意构造的skill完全可以在你不知情的情况下让agent执行危险操作比如读取本地敏感文件并写入日志。所以我在社区里推荐skills时始终坚持一句话不要因为一个仓库star数高就无条件信任看过核心代码再上生产。4.4 关于skills市场的现状现在网上已经出现了一些主打skills市场的站点概念上很像手机应用商店。但多数还处于野蛮生长状态审核机制不透明、skill质量参差不齐、更新维护也跟不上。我的建议是心态放平把它当作品类信息的获取渠道而不是官方应用商店来依赖。真正好用的skills有很大一部分还是藏在GitHub仓库和博客文章里。等这个生态成熟到有像样的安全审计机制之后再去市场里批量安装也不迟。5. 从模仿到独立设计我的Agent Skills学习路线5.1 第一层先当一个会用的装配工如果你完全没接触过agent开发不要从自己写skills开始先学会装配别人写好的技能。具体操作是装一个支持skills框架的工具比如Claude Code或OpenCode。把一个热门的skills合集clone下来逐个看它是怎么写的。在项目里实际调用几次感受一下技能触发、执行、产出的完整链路。每看一个skill就回答三个问题它解决什么场景它的执行步骤有没有依赖外部资源如果我要调整它的输出格式需要改哪个部分这个阶段的目标不是理解每一行代码而是建立skill如何影响agent行为的直觉。很多人一上来就啃源码结果被框架细节淹没反而拖慢了学习进度。5.2 第二层改别人的skills建立自己的套路用熟一批skill之后开始做局部改造。比如把一个英文论文排版skill改成中文论文版本把一个通用前端组件生成skill改成你团队技术栈专用的版本。改的时候你会自然地碰到metadata怎么写、步骤怎么拆、辅助脚本怎么调用这些具体问题。我自己的一个复制经验是保留骨架替换内容。别人的skill在步骤拆解和输出规范上通常经过验证这些是最有价值的部分不要轻易推翻需要动的是针对你业务场景的模板文件、依赖脚本和触发条件。这样改造出来的skill既保留了前人踩坑后的稳定性又贴合了自己的实际需求。5.3 第三层从项目全局设计skills全集到第三层就不再是单点写skill的问题了而是要从一个agent项目的整体架构出发设计一套skills集合。我通常会先画一张能力地图这个agent会面对哪些类型的任务每个任务需要走几步哪些步骤是多个任务共用的。举个例子一个文档处理agent的能力地图可能是这样文档接入读取PDF、Word、Markdown统一转换格式。文档分析摘要提取、关键词提取、结构拆分。内容生成按模板生成报告、翻译、改写。输出排版LaTeX排版、HTML导出、PPT整理。四个能力区域里每个区域配1到2个skills。共用部分比如格式转换可以单独做成一个基础skill供其他技能内部调用。这样做最大的好处是任何一个环节升级了只需要替换对应的独立skill不用把整个agent推倒重来。5.4 用agent evals给skills做验收最后说说评估。很多人写完skills之后不测试就上线这是不对的。现在社区里提到的agent evals就是一套专门用来评估agent行为的数据集和评测框架。我用的是最简单的一种模式给每个skill准备5到10个典型输入跑一遍看输出是否符合预期把这组测试固化成脚本每次改动skill后都重新跑一遍。测试集里我会故意放几个边缘情况比如空输入、格式异常输入、超出skill边界范围的请求避免agent在遇到非典型情况时行为失控。这一层看着花时间但对长期维护特别划算。skill这个东西随着你反复修改很容易出现改好了一个场景、搞坏了另一个场景的情况。没有自动化回归你只能靠手动重测所有场景迟早会漏。我后来把eval直接挂到git hooks里每次提交前自动跑基本告别了上线后才发现某个skill悄悄坏了的尴尬。5.5 给自己的一个建议如果你准备深入研究agent开发可以给自己定一个三个月的行动计划第一个月主攻读别人skill 复制改造第二个月开始写自己领域里的专有skill第三个月把多个skill组合成一个完整的agent工作流并配上自动化评估。三个月之后你再回头看最初那些为什么我的agent总是表现不稳定的问题大多数都能找到答案——不是因为模型不够强而是你还没有把能力沉淀成可以被复用的技能包。我在最初折腾agent项目时最大的体会就是不要急着让agent变得更聪明先让它变得更规范。skills看起来只是管理提示词的一种方式但它背后代表的是让agent行为可预期、可复用、可评估的工程化思路。这个思路一旦建立起来后面无论是换框架还是上生产你都不会慌。
Agent Skills实战指南：从提示词到可复用技能包
1. Skills是什么以及它为什么不是更长的提示词1.1 我为什么突然开始认真整理agent skills前阵子给项目做一次例行重构发现整个agent项目里散落着十几个临时提示词今天加一段请你用Python计算明天补一句请按LaTeX格式输出。结果agent的表现时好时坏换一个任务描述方式输出格式就变了稍微改一下语境它又退回了通用大模型的默认行为。后来我把这些临时提示词整理成一个个独立的skills情况立刻不一样了。同样的操作稳定性和可复用性完全是两个级别。这次经历让我觉得很多刚接触agent开发的人对skills的理解可能还停留在skills就是写一段更长的提示词给AI看这个误区值得单独拿出来说说。这篇文章会围绕agent skills到底是什么、手写一个完整的skills要经过哪些步骤、主流agent框架里skills的存储和加载方式有何不同、以及如何筛选第三方skills这几个问题展开。适合刚入门agent开发、或已经在用Claude Code、Codex这类工具但不太熟悉skills机制的读者。1.2 从提示词到skills到底进化了什么拿日常工作中的SOP来类比比较好理解。你给一个新同事口头说一句帮我把报告排一下版他大概率会按自己的想法来但如果你甩给他一份《排版规范》手册里面写了字号、行距、标题层级、目录生成方式、遇到特殊情况怎么处理他每次产出的东西就能保持稳定。skills本质上就是给AI agent用的这套操作手册。普通的提示词只解决当前这一步怎么做。它没有固定的输入输出契约没有可落地的执行步骤也不会去调用额外的脚本或工具。而一个合格的skills至少包含这几层触发条件什么任务下该启用这个能力得有清晰的适用范围不能什么都接。执行步骤把任务拆成有序的流程每一步给到agent可执行的动作而不是一句模糊的请尽力完成。输入输出约定预期拿到什么格式的数据、最终产出什么格式的结果必须写清楚。外部依赖可能需要引用一些参考文档、脚本、配置文件这些也属于skills的一部分。边界与兜底什么情况下要停下来询问用户什么情况下使用备选方案。所以skills不是更长的提示词而是一份可版本管理、可复用、可组合的能力包。你可以把一份写好的skills从Claude Code迁移到其他支持类似规范的agent上就像把员工的SOP手册复印一份给另一个部门同事用底层方法完全一致。1.3 skill和agent的区别一个是被调用者一个是执行体很多人在刚开始接触这个概念的时候会把agent有skills和agent就是skills搞混。我个人的理解是agent是负责调度、记忆、决策、调用工具的完整智能体而skills是agent可以装载的一个个独立能力模块。举个例子agent本身就像一个全科医生它知道什么时候该看内科、什么时候该看外科而skills就是内科、外科、眼科这些专科诊疗方案。全科医生可以在接诊时根据症状调用不同科室的诊疗流程医生本身不会因为换了一家医院就失去分诊的能力但这些专科方案是可以独立更新、被不同医院共用的。一个agent通常要同时管理记忆、对话上下文、工具调用和执行流程这部分是它作为执行体的职责skills则更聚焦在某一个具体领域该怎么干活。agent负责决定用什么skills负责把这件事做对。所以每次有人问skill和agent哪个重要我的回答都是它们是两个维度的问题根本不该放在一起比较。1.4 skills与agent记忆两个容易混在一起的概念还有一个高频困惑是skills和agent记忆有什么区别。简单说记忆是agent对过去交互历史的保存和检索它告诉agent这个用户上次选了哪种方案skills则是能力设定它告诉agent处理某类任务时应该按什么标准步骤来。我在项目里会把记忆和skills彻底分开管理。记忆放在向量库或结构化存储里由agent运行时读写skills放在独立的目录里用文件和脚本固化。这样做的好处是skills可以跨项目复制、可以交给别人review、可以单独测试而记忆跟具体业务数据强绑定混在一起只会让代码越来越难维护。如果说agent是被调度的执行体记忆是它脑子里的工作记录那么skills就是它的工具箱。三者分离各司其职agent项目才能撑到一定规模而不烂掉。2. 手写一个Skills文件的完整过程拿LaTeX排版Skills练手2.1 需求拆解先给这个skill画出边界直接上手写skills之前最忌一上来就动笔写步骤而应该先想清楚这个skill的边界。以LaTeX排版skill为例——这个需求在论文写作、竞赛报告场景里特别常见我群里已经有三四个人问过怎么做一个latex排版skills了。我先拆需求触发场景用户给出一个Markdown或纯文本的文档结构希望得到规范的LaTeX源码。输入文档标题、章节层级、是否有表格、引用格式要求、中英文混排要求。输出一个可直接编译的.tex文件包含完整导言区和正文中文场景下需要指定合适的ctex或xeCJK方案。边界不负责具体内容的生成只负责排版骨架不处理复杂的自定义宏包因为那通常需要人工确认。这个边界很重要。如果不在skill里写明只负责排版骨架不负责内容创作agent很可能越界帮你把正文也扩写一遍产出的内容反而没办法直接用。2.2 目录结构不该只有一个markdown文件很多初学者以为skills就是一个文本文件这也是误区之一。拿我现在项目里实际在用的结构举例一个完整的skills一般长这样latex-format/ ├── SKILL.md ├── references/ │ ├── 中文学位论文模板.tex │ ├── 英文会议模板.tex │ └── 表格与插图规范.md └── scripts/ ├── check_latex.sh └── escape_special_chars.pySKILL.md是主描述文件agent优先读它来决定这个skill怎么用references放参考文档和模板scripts放可执行的工具脚本比如检查生成的TeX文件能否被常见编译器解析。不要把所有的东西都塞进一个SKILL.md。主描述文件最好是说明书而不是百科全书它负责告诉agent有哪些资源可以用、按什么顺序用具体细节放在references里按需读取这样能节省上下文窗口也让整个skill更容易维护。这个设计思路我是在看了不少开源skills之后才摸清楚的一开始我也习惯把所有细节都堆进一个文件结果每次调用都吃掉大量上下文还容易让agent抓不住重点。2.3 一个可以直接套用的SKILL.md实例下面这个是我实际在用的LaTeX排版skill简化版你可以直接抄去改--- name: latex-format description: 将Markdown或纯文本内容转换为规范的LaTeX源码。适用于学术论文、技术报告、竞赛文档等场景。 --- # LaTeX排版助手 ## 触发条件 - 用户要求生成LaTeX代码或将文本转换成LaTeX格式 - 用户明确提到论文、报告、竞赛文档排版需求 ## 输入 - 文档标题 - 文档类型article/report/book - 是否包含表格、图片、公式 - 中英文格式要求 ## 执行步骤 1. 检查用户提供的文档结构提取标题层级。 2. 在references/中寻找与用户场景最接近的模板文件。 3. 根据模板生成tex文件骨架 - 中文文档使用ctexart文档类 - 英文文档使用默认article字体设为Times New Roman兼容方案 4. 将正文内容逐段填入注意 - 特殊字符如 % # _ { } 需要转义 - 图片路径统一使用relative/path引用 - 表格使用tabular环境统一列宽 5. 运行scripts/escape_special_chars.py 检查转义问题。 6. 运行scripts/check_latex.sh 检查括号配对和begin/end配对。 ## 输出格式 返回一个完整的.tex文件源码并附使用说明包括使用的编译器xelatex/pdflatex和注意事项。 ## 注意事项 - 不要随意添加未在模板中出现过的宏包。 - 用户要求定制样式时先询问清楚再动手。 - 如果内容中包含复杂表格或公式布局先给出方案让用户确认再生成完代码。这段内容里的metadata部分name和description是给agent做匹配用的描述写得越具体触发越精准。步骤部分则要遵循一个原则让agent每一步都能产生一个可检查的中间结果而不是让它一口气做一个大黑盒操作。2.4 调试技巧如何避免执行到一半报错写skills的人大概率都见过类似agent execution terminated due to error.的报错。我第一次看到这个报错的时候以为是自己提示词写得有问题反复修改措辞都没用。后来排查才发现问题出在skill里引用了一个不存在的脚本路径agent按照步骤执行到第三步发现文件找不到整个流程直接终止。这个报错本质上不是提示词写错了而是skill的资源完整性出了问题。现在我的排查顺序已经固定成一套套路检查SKILL.md中引用的每一个references和scripts路径确认相对路径在skill目录内真实存在。检查scripts是否有执行权限如果涉及shell脚本先手动跑一遍确认退出码为0。检查步骤之间的依赖关系务必确保前一步的输出格式是下一步能直接读取的。在SKILL.md里加一条兜底如果执行过程中出现无法解决的错误应该向用户报告错误原因并停止而不是强行继续。还有一个很多人不知道的技巧给skill目录加一个tests/子目录放几个典型的输入输出用例。即使agent工具本身不运行测试你在调试阶段也可以手动模拟一次完整调用看看哪个步骤会断。这一步能帮你省下大量和报错搏斗的时间。3. 主流Agent框架里Skills的存放与加载方式对比3.1 Claude Code手动安装GitHub上Skills的方法Claude Code是目前把skills概念贯彻得比较彻底的工具之一。它会在项目目录里找.claude/skills/这样的目录结构每个子文件夹就是一类skill里面同样是一个SKILL.md加若干辅助文件。从GitHub上装一个第三方skill本质上就是把它克隆到对应目录然后在Claude Code里重新加载。实际手动安装的步骤大致是在GitHub上找到目标skills仓库通常是xxx-claude-skills这类名字。把仓库clone下来或者单独下载某个skill文件夹。放进项目的.claude/skills/或全局配置对应的skills目录。在Claude Code里重启会话或运行技能加载命令让新skill生效。听起来很简单但很多人会栽在执行权限上。GitHub上的skills经常带.sh脚本clone下来后这些脚本默认没有执行权限agent调用时就会报错。所以我在装完每个skill后的第一件事就是检查目录里的脚本是否有x权限。3.2 Codex与OpenCode文档化知识包路线OpenAI Codex这条线和Claude Code的skill机制就不太一样。它更依赖AGENTS.md这类项目级规范文件把说明文档放在固定位置agent在进入项目时自动读取然后按文档里定义的规则来执行任务。这种方式下你说的skills更像一套知识包强调的是让agent理解项目的背景和约束而不是给它一个可调用的函数。OpenCode也有类似的机制支持用户定义命令、agent规则、项目说明文档。我在OpenCode里更习惯把技能设计成一个个独立的命令输入一个路径或参数就能让agent按预设流程处理。这两种思路其实是互补的Claude式skills偏向流程编排把步骤固化下来Codex式偏向知识注入让agent读文档之后自己规划。如果你项目里既有完整流程又希望agent保留一定的自主性可以考虑混用但前提是你得清楚每个skill在哪一层生效。3.3 浏览器Agent类工具另一种skill形态说到Pi Agent、Hermes Agent这类最近比较活跃的开源agent它们的skill形态又不一样。这类agent主要工作场景是浏览器自动化所以它的skills往往是一组可复用的浏览器操作指令包比如打开某个页面、定位元素、点击按钮、提取数据这一整串动作可以被封装成一个skill下次遇到同类型网站时直接调用。和写LaTeX这种文档类skill相比浏览器操作类skills的调试难度更高因为页面结构经常变。我给这类agent写skills时会刻意把选择器定位和业务动作拆开放在两个文件里。页面改版了只需要更新选择器那一层不需要动整个业务逻辑。如果你不是特别清楚某个agent支持哪种skill格式先找一个官方sample拆开看看比自己摸索快得多。3.4 不能漏掉的Superpower Skills合集聊skills推荐很难绕过superpower skills这个项目。它的思路是把一套相对完整的工作方法论打包成一堆skills比如任务拆分、代码审查、技术方案设计每个技能都是单独的markdown文件组合起来用效果非常好。这个合集受欢迎的原因其实不在某个单独的skill写得多惊艳而是它的体系感很强它会引导agent先思考、再规划、再执行、最后反思整个流程符合高素质工程师做事的习惯。我在项目里借用过它的任务拆分skill改造后几乎成了我所有agent项目的标配。安装它通常是直接clone仓库到Claude Code对应的skills目录具体路径每个版本可能有差异以仓库README为准。需要注意这类合集更新频繁不建议直接修改原文件而是把自己定制的版本放到独立目录里方便以后合并上游更新。3.5 各框架skills对比一览框架/工具skills的主要形式启用方式适用场景Claude Code.claude/skills/目录中的SKILL.md 脚本文件放入目录后重启会话或加载完整流程编排、本地脚本调用CodexAGENTS.md等规范文档启动时自动读取项目级约束、知识注入OpenCode命令、规则、文档配置文件中注册轻量命令与自主规划结合Pi Agent / Hermes Agent浏览器操作指令包按工具说明导入网页自动化、数据采集Superpower Skills成套方法论文档clone到skills目录通用任务规划、代码工作流这里有个心得当你在不同框架之间切换时不要指望同一个skill文件能原样到处跑但它的设计思路完全可以迁移。重要的不是文件格式而是你在这个skill里沉淀的步骤、边界和输出规范。4. 日常收藏的Skills源以及筛选第三方Skills的避坑经验4.1 值得定期翻一翻的GitHub仓库类型找skills和找开源库不一样很难靠一个搜索词就命中所有好东西但有一些固定的矿脉值得定期去翻awesome系清单仓库搜awesome-claude-skills、awesome-ai-agents这类聚合仓库里面会按用途分类整理社区里比较成熟的skills。竞赛和论文相关的skills仓库数模竞赛场景尤其典型。每年比赛前我都会看到有人把常用的数学模型、论文排版规范、数据分析流程整理成一组skills比赛时让Codex直接调用。这种时效性强的skills仓库问题在于很快过时但拿来当灵感来源非常合适。特定垂直领域skills比如前端开发skills这类仓库会把一个前端任务从组件结构、样式方案到代码规范完整固化下来。如果你经常用agent生成前端代码这一类是刚需。我用一个本地目录专门收集这些仓库的链接并且给每个仓库打上标签流程型、知识型、工具型。这样找到新skill时先归类再决定要不要装进agent项目里。4.2 图像生成、设计类Skills值得装吗热词里有图片生成skills安装包和ai漫剧常用skills说明图像生成也是大家普遍关心的方向。图像生成类skills和排版类的本质差别在于图像生成的关键在提示词结构、参数调优和出图后的筛选逻辑。所以一份靠谱的图像生成skill通常会把提示词拆成主体、风格、构图、光影、负面提示词几个部分并规定一个先生成草稿供用户确认再出大图的工作流避免用户直接等待昂贵的多轮生成。这类skill我建议优先用社区里经过验证的版本而不是自己从头写。原因是图像生成的坑非常多比如中文字体乱码、长宽比触发生成模型上限、负面提示词和正面提示词冲突等等这些都是社区用真金白银的API费用试出来的经验自己重新踩一遍成本太高。4.3 装第三方Skills前必须检查的几件事第三方skills虽然能提升agent能力但也伴随风险。因为skill本质上是把一段指令和脚本交给agent执行所以必须谨慎。我给自己定了几条硬规矩分享出来供参考看脚本内容不只看描述。任何带.sh或.py的skill我都会先打开脚本通读一遍确认里面没有可疑的下载、上传环境变量等行为。这一步花不了几分钟但对agent安全至关重要。在隔离环境里试跑。新装的skill先在测试目录或沙箱环境里跑一次确认行为符合预期再放进正式项目。检查依赖引入方式。skill里如果写死了某个外部URL要警惕后续版本变更带来的供应链风险。优先选择不依赖外部动态内容、或者依赖内容可锁版本的skill。留意触发描述的覆盖范围。有些skill的description写得特别宽泛比如处理任何文档任务这会让agent在无关任务上也频繁调用既浪费时间又可能产生错误结果。发现这种情况我会手动收窄触发条件。这里展开说一下agent安全的问题。一个恶意构造的skill完全可以在你不知情的情况下让agent执行危险操作比如读取本地敏感文件并写入日志。所以我在社区里推荐skills时始终坚持一句话不要因为一个仓库star数高就无条件信任看过核心代码再上生产。4.4 关于skills市场的现状现在网上已经出现了一些主打skills市场的站点概念上很像手机应用商店。但多数还处于野蛮生长状态审核机制不透明、skill质量参差不齐、更新维护也跟不上。我的建议是心态放平把它当作品类信息的获取渠道而不是官方应用商店来依赖。真正好用的skills有很大一部分还是藏在GitHub仓库和博客文章里。等这个生态成熟到有像样的安全审计机制之后再去市场里批量安装也不迟。5. 从模仿到独立设计我的Agent Skills学习路线5.1 第一层先当一个会用的装配工如果你完全没接触过agent开发不要从自己写skills开始先学会装配别人写好的技能。具体操作是装一个支持skills框架的工具比如Claude Code或OpenCode。把一个热门的skills合集clone下来逐个看它是怎么写的。在项目里实际调用几次感受一下技能触发、执行、产出的完整链路。每看一个skill就回答三个问题它解决什么场景它的执行步骤有没有依赖外部资源如果我要调整它的输出格式需要改哪个部分这个阶段的目标不是理解每一行代码而是建立skill如何影响agent行为的直觉。很多人一上来就啃源码结果被框架细节淹没反而拖慢了学习进度。5.2 第二层改别人的skills建立自己的套路用熟一批skill之后开始做局部改造。比如把一个英文论文排版skill改成中文论文版本把一个通用前端组件生成skill改成你团队技术栈专用的版本。改的时候你会自然地碰到metadata怎么写、步骤怎么拆、辅助脚本怎么调用这些具体问题。我自己的一个复制经验是保留骨架替换内容。别人的skill在步骤拆解和输出规范上通常经过验证这些是最有价值的部分不要轻易推翻需要动的是针对你业务场景的模板文件、依赖脚本和触发条件。这样改造出来的skill既保留了前人踩坑后的稳定性又贴合了自己的实际需求。5.3 第三层从项目全局设计skills全集到第三层就不再是单点写skill的问题了而是要从一个agent项目的整体架构出发设计一套skills集合。我通常会先画一张能力地图这个agent会面对哪些类型的任务每个任务需要走几步哪些步骤是多个任务共用的。举个例子一个文档处理agent的能力地图可能是这样文档接入读取PDF、Word、Markdown统一转换格式。文档分析摘要提取、关键词提取、结构拆分。内容生成按模板生成报告、翻译、改写。输出排版LaTeX排版、HTML导出、PPT整理。四个能力区域里每个区域配1到2个skills。共用部分比如格式转换可以单独做成一个基础skill供其他技能内部调用。这样做最大的好处是任何一个环节升级了只需要替换对应的独立skill不用把整个agent推倒重来。5.4 用agent evals给skills做验收最后说说评估。很多人写完skills之后不测试就上线这是不对的。现在社区里提到的agent evals就是一套专门用来评估agent行为的数据集和评测框架。我用的是最简单的一种模式给每个skill准备5到10个典型输入跑一遍看输出是否符合预期把这组测试固化成脚本每次改动skill后都重新跑一遍。测试集里我会故意放几个边缘情况比如空输入、格式异常输入、超出skill边界范围的请求避免agent在遇到非典型情况时行为失控。这一层看着花时间但对长期维护特别划算。skill这个东西随着你反复修改很容易出现改好了一个场景、搞坏了另一个场景的情况。没有自动化回归你只能靠手动重测所有场景迟早会漏。我后来把eval直接挂到git hooks里每次提交前自动跑基本告别了上线后才发现某个skill悄悄坏了的尴尬。5.5 给自己的一个建议如果你准备深入研究agent开发可以给自己定一个三个月的行动计划第一个月主攻读别人skill 复制改造第二个月开始写自己领域里的专有skill第三个月把多个skill组合成一个完整的agent工作流并配上自动化评估。三个月之后你再回头看最初那些为什么我的agent总是表现不稳定的问题大多数都能找到答案——不是因为模型不够强而是你还没有把能力沉淀成可以被复用的技能包。我在最初折腾agent项目时最大的体会就是不要急着让agent变得更聪明先让它变得更规范。skills看起来只是管理提示词的一种方式但它背后代表的是让agent行为可预期、可复用、可评估的工程化思路。这个思路一旦建立起来后面无论是换框架还是上生产你都不会慌。
