Agent Skills 完全指南：从零开发到实战调优，让AI掌握可复用技能

去年年底的时候，我开始重度使用 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 安装方式各有特点，我直接总结成一张表格方便对比。

实际安装非常简单，基本就是三步：从社区仓库克隆 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 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 的理解上一个台阶。做完了再回来看看这篇博客提到的其他内容，相信你的体会会很不一样。