最近几个月AI编程圈子里的热词换了一波又一波从Agent到MCP再到眼下的Skills节奏快得让人跟不上。如果你也关注Claude Code、Codex、OpenCode这些工具会发现“agent skills”这个概念几乎被所有主流Agent框架同时捧上了台面。官方文档里把它定义成一种让Agent获得专业能力的方式社区里则直接把它当成“给AI装外挂”的标准手段。我自己的体会是Skills本质上就是一套写给Agent看的技能说明书和工具包的组合体。它跟提示词不一样不只是一段话它跟插件也有区别不只是被动等待调用。Skills更像是一种以SKILL.md文件为入口、附带脚本和资源的完整能力包。这篇内容我会把Skills是什么、怎么开发、怎么安装、怎么避坑一次讲透其中大部分细节来自我实际跑通项目后的经验总结尤其是那些文档里不会明说的坑。1. Skills在Agent体系里到底扮演什么角色要搞清楚Skills得先理解Agent现在的运行方式。目前的AI Agent尤其是编程类Agent基本都遵循“思考-行动-观察”的循环模型先生成决策然后调用工具执行动作再根据返回结果调整策略。早期大家把注意力放在模型本身的能力上后来发现工具调用的质量才是决定Agent实战效果的上限。Skills恰好就是用来提升工具调用质量和任务完成深度的关键一环。1.1 为什么Agent都在卷Skills我最早注意到Skills这个方向是因为Claude官方推出Agent Skills之后社区一下子冒出了大量第三方Skills仓库。紧接着OpenAI的Codex、谷歌的OpenCode也跟进了类似机制。它们虽然命名上略有不同但思路完全一致与其让模型在各种复杂指令中反复试错不如把某类任务的完整工作流程、注意事项、代码模板、脚本工具全部封装成一个人可读、模型可解析的目录调用时直接加载。这背后有一个很现实的问题大模型虽然有海量知识但它的“常识”和“专业操作规范”并不总是一回事。比如写一个LaTeX文档模型知道LaTeX语法却不一定清楚期刊模板的目录结构、常见宏包冲突、编译工具的调用参数。这些信息如果全部塞在系统提示词里很快就把上下文撑爆了。用Skills把这类知识按需加载模型在需要时才会去读取和调用上下文占用极小效率却高得多。再往深一层想Skills其实是把“怎么做好一件事”的隐性经验显性化了。我试过对比同一模型在装了Skills和没装Skills时处理同一类任务的效果结果差异非常明显没装Skills时模型会给出一个“看起来不错但细节粗糙”的结果装了Skills后它会主动按照技能里的步骤走连文件命名、错误检查、边界处理这些细节都会照顾到。这就是专业化封装带来的提升。1.2 Skill、Agent、Workflow三者间的边界很多人在学习Skills时会被几个概念绕晕Skill、Agent、Workflow到底有什么区别简单理解Agent是执行者它负责理解目标、拆解任务、调用工具Workflow是固定流程适合路径明确、步骤不变的任务Skill则是一个个能力模块Agent可以在任何合适的时机动态加载它。拿做饭来类比Agent是厨师Workflow是标准化菜谱比如“红烧肉三步法”Skill则是厨师的专项技能包比如“刀工大全”“火候控制手册”。厨师做菜时会根据今天要做的菜决定用哪本手册用手册里教的方法处理食材。Skills的灵活性就在于它不需要提前编排流程Agent自己会判断什么时候该用到它。还有个容易混淆的概念是harness。在Claude Code这类工具里harness是指承载Agent运行能力的完整外围框架包括命令解析、工具注册、权限控制、上下文管理等Skills则是harness之上的一层知识增强机制。说直白点harness是骨架Skills是附着在骨架上的专业技能。很多人误以为Skills是独立运行的程序其实它必须寄生在一个成熟的Agent框架里才能发挥作用。1.3 Skills与MCP、Function Calling的关系既然提到了工具调用就绕不开与MCP模型上下文协议和Function Calling的对比这也是社区里讨论频率很高的话题。Function Calling是模型与外部函数交互的基础协议它解决的是“模型如何触发外部动作”的问题MCP把这种交互标准化实现了“一套接口接入多种工具”Skills则站在更高一层解决的是“模型拿到复杂任务后如何按最佳实践完成”的问题。实际项目中Skills和MCP经常搭配使用。MCP负责提供工具接口Skills负责提供方法论。比如我开发过一个图片处理的Skills里面写明了几种常见图片格式的特点、处理建议、推荐的脚本入口真正的图片处理操作则通过MCP服务执行。这样分工的好处是Skills描述经验MCP执行动作Agent负责编排各司其职。如果你已经在用MCPSkills不但不会冲突反而能把MCP工具的使用方式沉淀成标准流程让Agent用得更稳。2. 动手开发第一个Skills技能包概念讲完了直接进入实操。我会从一个最简单的Skills开发流程开始把目录结构、文件规范、SKILL.md怎么写这些细节全部过一遍。这套方法适用于Claude Code、Codex、OpenCode等主流框架差别只在于存放路径和加载方式这个后面会专门说。2.1 Skills的标准目录结构先看一个标准的Skills目录长什么样my-skill/ ├── SKILL.md ├── scripts/ │ ├── process.py │ └── utils.sh ├── assets/ │ ├── template.html │ └── reference.md └── config/ └── params.json核心是SKILL.md它相当于整个技能的说明文档和控制中心。scripts目录放可执行脚本assets目录放模板、参考文档、示例文件config目录不是必须的但如果技能涉及可选参数放一个配置文件会更规范。在这个结构里SKILL.md是唯一被Agent主动读取的文件其余文件都是按需引用的资源。这里有一个我在实际开发中总结的经验SKILL.md要写得“少而精”。模型读取SKILL.md时只会把它当作初始化信息如果写得太长占用了大量上下文反而会影响后续任务执行。最好的做法是SKILL.md只写概览、适用场景、使用步骤、脚本入口把详细的参考信息放到assets目录里让模型按需读取。2.2 编写一份高质量的SKILL.mdSKILL.md本质上是Markdown文件但为了能让模型准确解析最好加上YAML格式的frontmatter作为元信息。一份基础模板长这样--- name: latex-formatter description: 用于将普通文本转换为符合学术规范的LaTeX文档支持常见期刊模板。 ---# LaTeX格式化技能 ## 适用场景 - 将Markdown或纯文本转换为LaTeX - 生成符合标准期刊模板的论文结构 ## 使用步骤 1. 先读取assets/journal-template.tex 2. 根据模板结构调整正文结构 3. 调用scripts/convert.py生成最终.tex文件 4. 检查生成的LaTeX语法注意转义特殊字符 ## 注意事项 - 参考文献统一使用BibTeX格式 - 数学公式必须用$...$或\[...\]包裹 - 不要修改模板提供的宏包导入部分注意几个细节description字段要写得具体且包含关键词因为Agent会通过语义匹配来判断什么时候该调用这个Skill。我见过很多人的description写得太泛比如“处理文档”结果模型在根本不需要的场景下也尝试调用反而增加了干扰。使用步骤要清晰每个步骤最好对应一个可执行动作让模型不需要猜测。还有一点值得强调SKILL.md里的注意事项写得越具体模型执行越精准。比如你写“注意转义特殊字符”模型不一定知道哪些字符需要转义但如果你写“注意将%#_等字符前加反斜杠转义”模型就能准确执行。实操下来这种“指令即代码”的思路能让技能的稳定性提升一大截。2.3 参数设计与命名规范Skills的功能如果复杂最好在SKILL.md里声明支持哪些参数。比如一个“图片生成”技能参数可能包括输出尺寸、风格、格式、是否透明背景等。这些参数需要在SKILL.md中明确列出并说明默认值和可选范围。模型读到时就会知道在什么情况下该传什么参数。命名这块也有讲究。Skills目录名和name字段要保持一致且统一用小写字母加连字符。这个看起来是小事但我踩过坑给一个技能命名时用了下划线结果在某个Agent框架里加载异常排查半天才发现是命名规范问题。另一个经验是相比散装功能把某个完整任务做成Skills价值更高。比如“latex格式化”就比“latex加粗标题”实用得多前者是一个完整工作流后者只是一个小操作。在参数设计上建议保留一个默认参数文件让模型在用户没有明确指定时直接套用默认值。这能显著降低模型的决策成本也减少因为参数冲突导致的报错。想象一下用户只说“生成一张Logo图”模型读取SKILL.md后发现输出尺寸默认值为512x512、风格为扁平化它就可以立刻开始工作而不是反复追问细节。3. 从零搭建一个可复用的图片生成Skills理论说多了容易飘我拿一个真实的例子——图片生成Skills来完整走一遍开发流程。这个技能会集成一个外部绘图服务的能力并通过Skills的标准结构封装起来。下面是整个开发过程和实操记录。3.1 需求拆解与步骤规划先说需求背景。我平时需要在技术文章里配一些示意图以往的做法是打开绘图工具手动画效率很低。后来我用Agent生成图片但每次都要在提示词里写一堆参数而且模型输出不稳定。于是我决定把这个过程彻底封装成一个Skills让Agent只要接到“生成图片”的需求就自动按照固定流程执行。这个Skills的核心需求拆解下来有三块一是理解用户的图片描述把它转化成绘图API能理解的参数结构二是按设定的风格与尺寸生成图片三是把结果保存到本地并生成预览。这个过程中模型需要知道调用哪个脚本、传什么参数、结果输出到哪里这些信息全部写进SKILL.md。为了让脚本更易维护我把整个流程拆成了两个文件prompt_builder.py负责把用户的自然语言描述转换成API参数image_saver.py负责下载图片并保存到指定目录。这样模型调用时思路清晰脚本也各司其职。3.2 标准操作步骤演示接下来我分步演示一下这个Skills的实际开发过程。第一步创建目录结构。在skills目录下新建image-generator文件夹里面创建SKILL.md、scripts目录和一个assets目录。如果你是在Claude Code中使用通常路径是~/.claude/skills/image-generator/Codex环境下则是~/.codex/skills/image-generator/。第二步编写SKILL.md。除了基础元信息我把使用步骤写得非常具体先读取scripts里的脚本说明再调用prompt_builder.py完成参数转换然后请求绘图服务最后用image_saver.py保存结果。为了让Agent理解每一步的目的我在步骤描述里加入了必要的参数说明。第三步实现脚本。这里简单展示prompt_builder.py的核心逻辑#!/usr/bin/env python import json import sys def build_prompt(description, styleflat, size512x512): prompt fCreate a {style} style illustration: {description} params { prompt: prompt, size: size, format: png } return json.dumps(params) if __name__ __main__: desc sys.argv[1] if len(sys.argv) 1 else a simple diagram style sys.argv[2] if len(sys.argv) 2 else flat print(build_prompt(desc, style))脚本功能并不复杂但它的存在让模型的决策路径变得非常清晰脚本的内部逻辑无需模型关心。第四步在assets目录放一份风格参考文档。里面用图文方式展示了扁平化、拟物化、线稿等几种风格的代表图片和特征描述。这样模型在生成图片时如果用户提到了风格它就能通过参考文档精准匹配而不是凭感觉猜。第五步反复测试并调整SKILL.md的措辞。比如一开始我在步骤里写了“生成图片”这个表述太模糊模型不知道该生成什么格式改成“调用scripts/prompt_builder.py生成参数并请求接口用scripts/image_saver.py保存为PNG”后模型的执行准确率明显提升。3.3 实测效果与调试记录一个Skills开发完重点就是测。我测试时让Agent生成了一张“扁平化风格的API调用时序图”第一次跑下来图片是生成了但尺寸不对原因是SKILL.md里没有写明默认尺寸。我在参数设计里补上默认值后重测这次生成结果就符合预期了。我还遇到过模型忽略风格参数的情况它接到的需求是“简约风格”但最终生成的图看起来并不简约。排查发现SKILL.md中虽然列出了风格参数却没有给出每种风格的具体特征描述。我把assets/reference.md补全在每种风格下面增加了“适合场景、常用配色、构图特点”等信息后效果立刻改善。这个调试过程让我明白了一个道理Skills的核心不是代码而是模型调用代码时的决策上下文。上下文越精确输出越稳定。技术文档里通常只讲“怎么写SKILL.md”但没有告诉你SKILL.md里的每一句话都可能影响模型行为这也是为什么我建议开发Skills时一定要反复测试、逐步打磨。4. 安装、部署与跨工具复用Skills开发好之后真正决定它是否好用的往往是安装和部署环节。不同Agent框架加载Skills的方式略有差异下面我会逐个说清楚并分享一些跨工具复用的经验。4.1 Claude Code、Codex与OpenCode的Skills目录差异虽然Skills概念在各家Agent里逐渐统一但存放路径并不完全一致。Claude Code是目前对个人用户最友好的官方文档明确支持~/.claude/skills/目录同时项目级可以使用.claude/skills/。CodexOpenAI CLI的路径是~/.codex/skills/OpenCode则是~/.opencode/skills/。这里有一个跨工具复用的痛点同一套Skills如果分别复制到三个目录后续更新时容易漏掉其中一份。我的做法是用符号链接symlink把不同目录指向一个公共目录只维护一份源文件。操作上也简单Linux/macOS下用ln -sWindows下用mklink /D就能建链接。这样无论用哪个Agent加载的都是同一份最新版本。实际使用中我发现CodeBuddy这类国产Agent也开始兼容Claude的Skills目录规范知道这个消息后我直接把目录链接过去就能复用体验上基本无感。某种程度上说明Skills的生态正在形成事实标准Claude Code在这轮标准定义里占了先手。4.2 从GitHub安装第三方Skills的常见方式GitHub上有大量开源Skills仓库比如awesome-claude-skills这类聚合项目。安装第三方Skills时我会先明确几个问题这个Skill是否还在维护、SKILL.md文案是否清晰、脚本是否依赖特殊环境、有没有用户反馈的使用问题。安装步骤并不复杂。以Claude Code为例把Skills仓库clone下来把目标目录复制到~/.claude/skills/即可。不过直接在GitHub上装Skills更推荐用现成的Skills管理工具例如npx命令可以直接拉取远程Skills到本地方便管理类似包管理器的定位这类工具省去了手工整理目录的时间。如果你在GitHub上看到单个SKILL.md而不是完整的Skills目录不用怀疑这也算一种Skills。有些极简技能只有SKILL.md没有scripts和assets它们适合做纯方法论指导比如“代码审查规范”“Prompt优化指南”。安装方式同样很简单建一个目录把SKILL.md放进去就行。4.3 管理多个Skills的工程化经验Skills装多了以后管理就成了问题。我现在的做法是给Skills目录做分门别类开发类、写作类、设计类、数据分析类每一类下面再按具体技能建子目录。这样做的好处是当某个Agent框架加载Skills列表时信息更集中模型匹配成功率高也不容易出现互相冲突的技能。另一个实践经验是Skills不要盲目追求数量。我最初收集了二十多个Skills装了之后发现很多都用不上反而偶尔会干扰模型判断。后来我删掉了大约一半只保留实际项目中高频使用的那些体验明显改善。与其装一堆“看起来有用”的Skills不如把三四个核心Skills打磨到极致。维护Skills时版本管理也很重要。我会把重要的Skills目录放到Git仓库里每次改动都提交。这样一旦某个改动让Skill失效还能通过Git回滚到之前可用的版本。社区里有不少开发者用Tibo提出的“清理无用Skills”方法来控制Skills仓库膨胀核心思路就是定期审查每个Skills的使用次数和效果用数据决定去留。5. 常见的Skills源与高星项目推荐Skills的价值不仅在于自己开发还在于能够站在别人的肩膀上。这一节我整理一些高质量Skills源和适合不同场景的推荐仓库并分享如何判断一个Skills值不值得装的判断方法论。先说结论从Star数和更新时间看不出全部问题实际测一下才是硬标准。5.1 值得收藏的Skills仓库GitHub上目前热度最高的几个Skills聚合仓库基本都是围绕prompt工程的范例与实战经验库。最知名的是awesome-claude-skills收集了各种社区贡献的Skills从写作辅助到代码生成覆盖场景比较广。另一个方向是anthropics的官方技能示例仓库它提供的是官方标准格式的技能示例内容虽然不多但写法非常规范适合作为学习模板。在中文社区也有不少开发者在整理“中文友好的Skills集合”比如专门用于写公文、写周报、做PPT的技能包这些在特定场景下很实用。我建议刚接触Skills的人先逛这些聚合仓库把感兴趣的skills全部跑一遍再决定是否长期保留。测试成本远低于后期痛苦维护的成本。5.2 前端开发、写作、图片生成等高频场景推荐按我的使用频率以下几个场景最适合用Skills值得优先配置。前端开发是目前社区讨论最火的方向之一。用超级技能包Superpowers结合Claude Code可以做到“一句话生成完整组件”的效果不用反复调整属性参数。这类技能包整合了前端工程化的常见规范使用户无需手动键入每条细节模型会自动参照规范的校验原则与代码格式。实际体验下来生成代码的规范程度明显比裸提示词强不少。写作类Skills很适合自媒体和内容从业者。比如有的技能包内置了Markdown排版规范、标题优化规则、SEO关键词布局建议模型会按照这些规则输出文章初稿。我试过用写作类Skills生成技术教程效果比我自己手写还整齐。它不负责创作灵感但能把结构规范和表达水准稳定在地平线以上。图片生成Skills这类具体用法我在第三节已经演示过。实际项目里如果经常需要生成统一风格的配图Style参考与API封装组合能大幅节省重复沟通的时间。Codex多模态能力加持下这类Skill使用空间还在扩展有兴趣可以试试。5.3 如何判断一个Skills值不值得装判断Skills质量我选一个最简单且很难出错的筛选逻辑先看SKILL.md的description是否具体。如果description写得模棱两可比如“帮助用户完成各种任务”这种Skill大概率质量不高因为模型很难判断什么时候该召回它。再看是否有可执行脚本。纯文档型Skills不是不能用但可执行脚本通常意味着作者把操作细节都理顺了实践中也更容易落地。一个成熟的Skills仓库SKILL.md描述清晰、scripts脚本简单明了、assets资源完整三层都扎实这个Skills就可以装如果只有SKILL.md、内容还是抄来的模板那装了也是负担。我会特别留意SKILL.md里有没有“注意事项”这部分内容。真正的实战Skill作者一定会把踩过的坑写进去。如果一份SKILL.md通篇都是正面描述没有提到任何边界条件和注意点说明作者可能没有经过充分的真实场景测试这样的技能参考价值有限。基于这套判断标准既能帮你筛选优质技能也为你自己开发技能提供了改进方向。6. 常见报错与排查技巧实录Skills用多了自然会踩坑。这一节我把自己实际遇到过的高频问题整理成速查表包括报错信息、可能原因和解决思路。另外还会分享一套排查技巧帮你在问题出现时更快定位根因。6.1 高频错误与解决对照表下面这几种场景我基本上每个月都能遇到至少一两次。第一个是agent execution terminated due to error。这个报错算是最让人头痛的因为它信息量极少根本看不出问题出在哪。我遇到这个报错时一般先往前翻日志找到第一条Error的路径提示而不是盯着最终报错分析。大多数情况下是脚本依赖缺失或者路径写错了极少部分是Agent内部状态异常。如果连续出现且无明确日志我会直接重启Agent进程再复测同一指令。第二个是模型始终没有调用某个Skills。这种情况下通常不是Skills本身有问题而是model没识别到适用场景。我会检查SKILL.md里的description是否明确、是否包含任务关键词此外如果description里带了“这个技能适用于______”句式模型的理解度会明显好过一句“通用处理技能”。第三个是Skills能加载但执行结果不正确。高频触发条件是参数没传对、脚本路径写错、文件权限不足这几个。排查时先手动执行一遍脚本确认脚本本身没问题再检查SKILL.md里的调用方式与实际脚本参数是否一致。以下是常见问题的速查表报错/现象可能原因解决思路agent execution terminated due to error脚本异常、依赖缺失、路径错误翻日志找首条错误检查依赖与路径模型没有调用Skillsdescription表述模糊、场景不匹配重写description增加适用场景关键词Skills被调用但结果错误参数传递错误、脚本Bug、权限不足手动执行脚本验证校准SKILL.md调用参数多个Skills互相干扰技能边界重叠、description雷同合并或清理低质量Skills细分场景描述Skills加载后上下文占用过高SKILL.md过长、assets被大量读取精简SKILL.md正文将详细内容集中存放并按需引用6.2 排查Skills失效问题的三个步骤Skills失效的问题我在群里看到很多人只会盲目重装这是效率很低的做法。我会按固定流程排查这个流程基本能覆盖九成以上的问题。第一步确认Skills目录和文件名是否正确。很多问题出在大小写、下划线和连字符混用上。Skills的目录名和SKILL.md文件名必须精确匹配框架的规范稍有偏差就无法加载。我之前在Windows上把文件夹名写成了Image-Generator而skills配置里写的是image-generator结果Agent死活加载不到。第二步检查SKILL.md的frontmatter。这里要特别注意name字段是否与目录名一致description字段是否为空。有个别框架对frontmatter格式要求很严格YAML里的冒号后面必须加一个空格连markdown解析器都容不下这种格式疏漏。我遇到过几次skills无法识别的情况就是frontmatter里的冒号没加空格导致的。第三步运行脚本直接让Agent读取SKILL.md确认内容能正常加载如果读取正常则手动执行scripts里的脚本确认返回结果符合预期。如果这一步没问题但实战中还是不生效那问题基本出在模型对场景的识别上此时优先优化description的表述方式。6.3 安全性、性能与维护注意事项Skills本质上是一段可执行指令使用第三方Skills时它的安全性确实不能忽视。一个恶意的SKILL.md完全可以在你毫无感知的情况下指示Agent执行高权限命令、读取敏感文件、甚至上传数据。我的处理原则是不运行来路不明的脚本不安装需要提权操作的Skills。如果必须用就先读一遍SKILL.md和涉及的脚本内容确认没有可疑行为再装。性能方面的注意点主要集中在上下文占用和执行速度。SKILL.md写得太长模型每次调用都白消耗token速度也会受影响。我现在的习惯是控制SKILL.md篇幅详细内容按需引用。如果某个技能实在太复杂拆成多个SKILL.md互相调用反而更清晰性能也更好。维护方面最关键的是定期清理。每隔一到两周我会根据Git stats和人工印象删掉那些长期没有调用的Skills。很多积灰的Skills不但浪费时间还会增加Agent的备选项数量干扰决策速度。把Skills仓库维持在一个“少而精”的状态是我目前觉得最舒服的使用方式。写在最后从接触agent skills到做出第一个能稳定复用的技能包我最大的感受是这套机制真正把“经验”变成了可以复制、分发、共享的资产。以前写提示词效果全看语感现在做Skills效果靠的是结构设计加上反复测试。两者差距就像随手炒菜和按菜谱标准化出品前者有惊喜后者有保障。最近一次我还在用一个最近迭代出来的小技巧给SKILL.md里的每一条使用步骤配上“预期结果”描述。比如“运行脚本后图片会保存到output/目录并输出预览路径”。这个写法能让模型在某个步骤失败时通过比对实际结果与预期结果更早发现自己执行出错减少连带错误。别看这是一个很小的格式改动实测下来成功率提升了明显。如果你正准备接触或正在研究Skills我的建议很直接别空谈概念先拿一个高频小任务练手把它做成你第一个Skills。过程中你会遇到命名、路径、参数、描述、脚本、测试这一整套流程把这条链路跑通了后面再扩展其他技能就有章可循了。agent skills的价值从来不在“装得多”而在“用得准”这句话在我实践了几个月后的今天依然适用。