去年年底的时候我开始重度使用 Claude Code 和 Codex 这类 AI Agent 工具来写前端页面和整理数据很快就发现一个让人很抓狂的问题每次新建一个项目都要花十几分钟甚至更久把同一种页面布局、同一种数据处理逻辑、同一种代码规范“重新教”给 AI。明明这个 Agent 上个月才帮我写过一模一样的东西但这个月它又像是失忆了一样整体表现完全达不到预期。后来我接触到 agent-skills 这个概念才意识到问题出在哪里——我一直把“怎么做事”这一步丢给了模型临场发挥而不是把一套固定、可复用、经过验证的执行流程打包给 Agent。这篇文章就把我这段时间对 Agent Skills 的学习和实操经验完整整理出来包括它到底是什么、和 Agent 本身有什么区别、怎么开发自己的 skill、有哪些靠谱的 skills 来源以及实际使用中的各种坑。不管你是刚接触 AI Agent 开发的新手还是已经在用 Agent 写代码、跑数据的老手这篇文章应该都能帮你省下不少时间。1. Agent Skills 到底是什么先搞清楚它解决什么问题1.1 从一次手把手教 AI的经历说起先说一个我自己的真实案例。有段时间我需要批量处理几十个 CSV 文件做清洗和统计。每次把任务丢给 Agent它都会先问各种问题列名是什么、缺失值怎么处理、日期格式是什么样、要不要输出 Excel。我回答了一遍之后它总算跑起来中途还会因为写错 pandas 语法自己报错然后又试着修一遍。换下一个文件、换一种数据结构这个流程就要再来一遍。这就是没有 skills 的典型状态。Agent 的核心能力其实是临场反应它依靠模型的通用能力去理解任务、写代码、调工具但每一次它都在做新题。而 Agent Skills 做的事就是把一类任务的标准做法固化下来数据清洗有数据清洗的 skill生成图表有生成图表的 skill写 LaTeX 有写 LaTeX 的 skill。Skill 本质上就是一组指令、脚本、模板和参考文档的集合它告诉 Agent 这类任务应该按照什么步骤来做、用哪些工具、产出什么格式。用大白话说把 AI Agent 想象成一个新入职的实习生通用模型是实习生本身的聪明程度和学习能力而 skills 就是你们团队沉淀下来的标准作业流程和技术文档。实习生再聪明也得有一本工作手册才能稳定地把事情做对尤其是那些流程复杂、细节繁多的任务。1.2 Skill、Agent 和 Agent Framework 的边界到底在哪和不少朋友聊过之后我发现很多人分不清这几个概念。我自己的理解是这样的Agent 是一个能自主完成任务的智能体它可以做决策、调用工具、拆解目标并一步步执行它往往是面向一个完整场景的比如帮我写一个博客系统而 Agent Framework 是构建 Agent 的整套基础架构包括 LLM 接入、工具调用机制、上下文管理、执行循环这些底层能力像 LangChain、Anthropic 的 Claude Code、OpenAI 的 Codex CLI 都算在框架这一层。Skill 则完全不同它属于插件级别的存在不太管 Agent 怎么运行只管 Agent 在执行某一类具体任务时应该怎么做。一个 Agent 可以同时加载很多个 skills写前端时加载前端规范 skill处理数据时加载数据清洗 skill写学术论文时加载 LaTeX 排版 skill。Skills 不改变 Agent 的决策机制不会替换掉 Agent 的记忆系统更不会重新定义 Agent 能调哪些工具。它就是给 Agent 喂了几十页专业工作手册让它遇到对应的场景时能按手册来。我画过一个简单的类比Framework 是 Android 系统Agent 是一个安装了这个系统的手机而 Skills 就是手机里的一个个 App。没有 App 的手机也能打电话发短信但装了专业 App 之后它能干的活就完全不一样了。理解了这层区别你也就明白了为什么最近会有大量的skills 推荐skills 安装包之类的内容出现——大家都在给同一个 Agent 装不同的App来处理不同的专业场景。2. 动手开发一个 Skill从需求拆解到落地2.1 Skill 的标准结构与核心文件目前 Claude Code、Codex CLI 以及 OpenCode 等主流 Agent 框架对 Skill 的定义方式已经比较趋同了基本都是用文件夹加描述文件的方式。一个最标准的 skill 文件夹通常长这样my-skill/ ├── SKILL.md ├── scripts/ │ └── run.py ├── references/ │ └── api-docs.md └── assets/ └── template.html核心文件是SKILL.md它用来描述这个 skill 是干什么的、在什么场景下使用、以及调用的步骤是什么。这块内容非常重要因为 Agent 会先读它来判断当前任务是否匹配。如果SKILL.md写得含糊不清Agent 大概率会在错误的时机启用错误的 skill或者干脆不启用。scripts目录放可执行脚本references放参考资料和文档assets放模板和静态资源。这个结构不是硬性规定我自己见过很多变体但无论是官方文档还是社区实践都推荐用这种描述文件 脚本 参考材料的方式来组织因为 Agent 是逐文件读取的结构清晰会直接提升它的理解效率。2.2 实操从零写一个 LaTeX 排版 Skill 的完整过程之前看到热搜词里有怎么做一个latex排版skills这个我正好做过就拿它当例子完整拆解一下。我的需求是让 Agent 帮我写论文排版代码产出符合 IEEE 会议格式的 LaTeX 文档。第一步写SKILL.md的 frontmatter。这个部分给 Agent 提供元信息包括 skill 的名称和适合使用的场景。比如--- name: latex-formatter description: 用于生成和排版 LaTeX 论文文档适合在用户需要写学术论文、会议稿件、技术报告时使用。能够处理章节结构、公式、参考文献和图表。 ---第二步写SKILL.md的正文部分也就是执行步骤。这是整个 skill 的关键因为 Agent 会把它当作工作流程来执行。我写的不是你应该生成一个 LaTeX 文档这种笼统描述而是非常具体的操作序列# LaTeX 排版规范 ## 适用场景 - 写 IEEE、ACM 会议论文 - 生成技术报告、毕业论文 ## 执行步骤 1. 检查用户的输入内容识别文档类型和模板要求 2. 使用 IEEEtran 或 ACM 模板初始化文档结构 3. 正文部分按 摘要、方法、实验、结论 四段组织 4. 图表统一使用 figure 环境并设置 \caption 说明 5. 参考文献使用 BibTeX条目格式保持统一 6. 输出前编译检查修复所有报错 ## 质量要求 - 必须使用 \documentclass[conference]{IEEEtran} 作为论文类文档的基准 - 数学公式必须使用 amsmath 宏包 - 图表位置使用 t顶部和 b底部修饰符严禁出现浮动体遮挡问题第三步在references里放一份我自己整理的IEEE 模板常用命令速查表把\section、\subsection、\cite、\ref这些命令的用法和示例都写清楚这样 Agent 即使对某些命令印象不深也能通过速查表快速恢复记忆。第四步写一个简单的编译检查脚本scripts/compile_check.sh把pdflatex、bibtex和第二次pdflatex的完整编译序列打包起来Agent 只需要运行这个脚本就能完成编译检查不用自己一段段去拼命令。整套流程走下来我的体会是开发 skill 真正难的并不是写代码而是把自己的隐性经验显性化。你要把自己平时写论文排版时脑子里自动跑的那些判断规则一条条写出来——什么时候用表格、什么时候用图片、公式怎么编号、参考文献怎么去重。这些规则写得越具体Agent 的产出就越稳定。3. Skills 的安装、使用与日常调优3.1 主流框架下的 Skills 安装方式目前我实际用过的三种主流方式分别是 Claude Code、Codex CLI 和 OpenCode它们的 skill 安装方式各有特点我直接总结成一张表格方便对比。框架安装位置启用方式说明Claude Code~/.claude/skills/或项目.claude/skills/自动读取Agent 根据任务匹配社区生态最成熟大量现成 skills 可下载Codex CLI~/.codex/skills/自动读取可通过命名空间调用OpenAI 官方支持对代码任务优化明显OpenCode~/.config/opencode/skills/需要手动 enable灵活度高适合自定义场景实际安装非常简单基本就是三步从社区仓库克隆 skill 项目把文件夹放进对应的 skills 目录重启 Agent 会话。比如 Claude Code 装一个社区里的前端开发 skill我通常这样操作git clone https://github.com/example/frontend-dev-skill.git cp -r frontend-dev-skill ~/.claude/skills/装好之后可以先用一个简单的测试任务验证一下 Agent 是否真的加载了这个 skill。比如前端规范 skill 装完之后我直接丢给它一个给我生成一个登录页的任务看它是否主动套用了 skill 里的 HTML 结构规范和命名约定。如果它的行为没有变化大概率是 skill 的 description 写得不够好Agent 没识别出当前任务匹配这个 skill。3.2 使用姿势与参数调优技巧从我这几个月的实际使用经验看skill 用得好不好很大程度上取决于 Agent 框架本身的执行策略但也有一些参数可以自己调。比如 Claude Code 里有--skill标志位可以指定当前会话要加载哪些 skills我用它来处理多 skill 场景下的冲突问题。做过一次多 skill 联调同时加载了前端开发 skill和UI 设计规范 skill结果 Agent 输出页面的时候一会儿遵循前者的组件结构一会儿又套用后者的视觉规范风格比较混乱。后来我改成按需加载的方式在任务开始时只加载最核心的 skill跑完一个阶段之后再通过指令切换或追加新的 skill。这样既避免了上下文混乱也减少了 token 消耗因为每个 skill 的内容都会占用一部分上下文窗口。另外我还研究了一个进阶玩法给同一个 skill 写不同版本的SKILL.md分别用于快速生成和深度优化两种场景。快速版只给 Agent 最基础的步骤保证生成速度快、结构不跑偏深度版则加入大量质量检查和优化规则用来做第二轮评审和打磨。这样在同一个项目里我先用快速版把初稿铺出来再用深度版做精修整体效率比只用一个全能版 skill 高很多。4. 常用 Skills 源网站与选型建议4.1 值得收藏的几个 Skills 来源现在网上的 skills 资源已经不少了但质量参差不齐这里整理几个我实测下来比较靠谱的来源渠道。Awesome Claude Code Skills社区维护的 skills 合集仓库收录了大量经过验证的 skills从代码生成、文档写作到数据处理都有覆盖。我装的数据清洗 skill 就是从这儿找到的用起来很稳定。Anthropic 官方示例仓库官方团队的 skill 示例质量非常在线尤其推荐里面的文档生成和代码审查两个 skill。这个仓库我基本每次更新都会拉一遍看看有没有新玩法。个人博客和 Newsletter不少资深开发者在自己的博客上分享自制的 skills通常会附上完整的 SKILL.md 内容和设计思路。这类来源的 skill 往往带有很强的个人特色不一定通用但经常有非常巧妙的思路可以参考。除了直接拿来用我更推荐把别人的 skills 当作学习材料来拆解。我的习惯是每下载一个 skill先把它的SKILL.md通读一遍分析它的结构化编排方式、写作语气和上下文注入策略。看得多了之后你会发现那些好用的 skill 都有一个共同特征——它们把判断标准和例外情况写得极其详细能在 Agent 面对模糊场景时提供足够明确的指引。4.2 怎么评估一个 Skill 好不好用关于skills怎么测评这个问题我有一套自己总结的评估流程分享出来给大家参考。第一看它的 description 是否清晰。一个合格的 skill它的 description 里应该明确写出适用场景、触发条件和典型用法而不是笼统地说提供代码帮助。如果 description 写得模糊Agent 就很容易误判。第二检查它的执行步骤是否可验证。好 skill 里的每一步都是具体动作比如运行 npm run build 检查编译读取 config.json 并验证字段完整性这类。如果步骤是优化代码质量这种标准Agent 就会无所适从。第三用标准测试集跑一遍。我会给自己常用的每个 skill 建一个测试任务集里面放三到五个典型任务和一个边缘任务每次更新 skill 之后就跑一遍测试集对比输出质量。比如前端开发 skill 我会测试登录页生成、表单校验、响应式布局三个典型场景再加一个多语言支持的边缘场景。这套方法能比较客观地反映 skill 的真实水平避免凭感觉判断好坏。第四看维护活跃度。skills 这个东西和开源项目一样维护越频繁说明用的人越多、问题被修得越及时。我倾向于选择三个月内有更新的仓库而不是那种一年半载没动静的。5. 常见问题与排查技巧实录5.1 典型报错与解决方案实际开发和使用 skills 的过程中肯定会遇到各种报错。我把最常见的几类问题整理成速查表方便大家对照排查。问题现象可能原因解决方案Agent 没有启用对应 skilldescription 写得太宽泛触发概率低重写 description明确适用场景和关键词skill 里的指令被忽略指令太多太杂Agent 上下文溢出精简步骤把详细内容移到 references 目录脚本运行报错command not found缺少运行时依赖在 SKILL.md 里补充依赖安装步骤Agent 输出和 skill 规范不一致多个 skill 同时加载互相冲突改成按需加载每次会话只启用一个主 skillskill 生效过一次后不再生效会话过长导致旧指令被覆盖重新开启会话或手动重新加载 skill这里重点说一下agent execution terminated due to error这种报错如果你也遇到过通常不是 skill 本身写错了而是 Agent 在执行某个步骤时陷入了死循环或者触发了框架的安全限制。我的排查经验是先让 Agent 改用小步执行模式把一个大任务拆成多个小步骤每步输出中间结果并确认然后仔细看退出前最后一段日志通常那里已经写明了是哪一步出了问题最后检查 skill 里是否有互相矛盾的指令这也是导致 Agent 反复横跳的常见原因。5.2 独家避坑经验最后分享几个我踩过坑之后总结出来的经验这些东西很少会写在官方文档里。第一skill 不是越多越好。我有一段时间疯狂收集各种 skills一个 Agent 里装了二十多个结果反而是负优化。每次任务进来Agent 都要花大量 token 去筛选该用哪个 skill经常选错而且上下文被严重占用。后来我严格控制数量每个 Agent 只保留三到五个真正高频使用的 skills效果明显提升。第二注意 skill 的安全边界。现在 skills 可以从各种渠道下载里面装的可能不光是文本指令还会有脚本文件。这些脚本运行时的权限和你的本地用户权限是一样的所以在安装第三方 skill 之前建议先查看它的SKILL.md和脚本内容确认没有可疑操作。不要觉得麻烦这个检查习惯真的能帮你避开不少风险。第三善用社区但保持独立思考。像 hermes agent superpower skills 这类话题在社区里讨论度很高很多新推出的 skills 被吹得天花乱坠但实际用起来并不一定适合你的业务场景。我更建议在了解清楚一个 skill 的设计原理之后再决定是直接使用、修改定制还是从零写一个适合自己的版本。别人的 skills 是很好的学习材料但真正好用的其实是那些和你的工作流深度匹配的定制版本。第四版本管理要跟上。我会把自己常用的 skills 放进一个 git 仓库里管理每次修改都留下记录。这样即使某个版本的 skill 在升级后表现变差了也可以随时回退到之前的稳定版本。这个习惯在技能开发迭代比较快的时候特别有用推荐给大家。6. 如何规划 Agent Skills 学习路线6.1 按阶段制定学习和实践路径关于agent skills和agent开发学习路线这类关键词的热度一直很高说明有不少人正在入门这个方向。结合我自己的学习过程我总结了一条比较平滑的路径供大家参考。第一个阶段是会用花几天时间把 Claude Code 或 Codex CLI 装好去网上找几个口碑好的 skills 安装包体验一下装完 skill 之后 Agent 行为的变化。这个阶段不追求自己写只用感受有 skill 和没有 skill 到底差在哪。第二个阶段是会改选一个你用得最多的 skill尝试修改它的SKILL.md加几条你自己的规则进去看看 Agent 会不会按你的新规则执行。改坏了也不怕大不了删掉重装。这个阶段主要是建立skill 是被 Agent 逐字读取并执行的心智模型。第三个阶段是会写从自己的日常任务里挑一个重复性最高的场景按我前面写的流程从零开发一个 skill。过程中你会体会到把隐性经验显性化的难度也会慢慢形成自己的写作风格。第四个阶段是会评到这一步你基本可以加入社区的技能测评讨论也开始有能力评估别人的 skill 设计是否合理。到这个时候你就不再是 skills 的使用者而是创作者了。6.2 值得关注的进阶方向skills 本身只是起点真正有意思的是它和 Agent 生态其他部分的联动。我自己接下来在关注这几个方向。多 skill 协同工作流。单个 skill 的能力始终有限但几个 skill 组合起来就能覆盖一个完整的业务链路。比如我现在在做一个数据分析报告自动化的组合方案数据清洗 skill 处理原始数据图表生成 skill 画可视化LaTeX 排版 skill 产出最终报告。三个 skill 串联在一起整个流程几乎不需要人工干预。带记忆的 skill 系统。目前大部分 skill 是无状态的每次执行都从零开始。但如果能让 skill 结合 Agent 的记忆系统把上次任务的结论和偏好存下来下次执行时自动继承那效率还会有一个很大的提升。这个方向目前刚起步参考agent记忆的热度就知道大家都很关心。skill 的质量评估体系。随着 skill 数量越来越多客观评估一个 skill 好坏会变得越来越重要。我在尝试把我在测试集里用的那套方法做成更标准的评估框架希望能用一些量化指标来比较两个 skill 在相同任务上的表现差异。如果你正在思考自己的 agent 开发方向我建议从你自己的工作流里找一个用了三次以上的重复任务把它变成你的第一个 skill。这个过程本身就会让你对 Agent 的理解上一个台阶。做完了再回来看看这篇博客提到的其他内容相信你的体会会很不一样。