“agent-skills”这个词，我看到它挂在不少人的书签、GitHub star 和笔记大纲里，但真问一句“你给 agent 写过 skills 吗”，十个人里多半会卡壳。过去一年，我花了很多时间折腾 agent 开发，从最早写一长串 prompt，到后来自己手搓技能库，再把这套东西搬进团队项目，中间踩过的坑、推翻过的设计，凑在一起刚好够写一篇不太一样的分享。这篇文章不聊高深理论，只讲我实测验证过的理解、目录结构、代码和排错思路，适合正在学 agent 开发，或者想让 Claude Code、Codex 这类工具真正“能干细活”的人。
1. 先把“skills”这个词说透：它不是提示词，也不是插件
1.1 一个反直觉的起点：模型没变，变的只是技能包
我最早用 Claude Code 时，总觉得模型忽神忽鬼，让它干同一件事，今天靠谱明天跑偏。后来看会话日志才发现，问题不在模型，而在“每次都得重新把流程讲一遍”。你跟它说“帮我写一份建模比赛论文”，它只能凭通用常识发挥；你对它说“先加载 report-skill，按里面的模板排版，再调用 compile.sh 编译”，它就能稳定输出符合格式的 PDF。
这就是 skills 存在的根本原因：大模型的上下文窗口再大，也没法在每次对话里完整背诵一套几十页的操作规范。Skills 的本质，是把显性的领域知识、操作流程和可执行脚本打包成一个“按需加载的经验模块”。模型平时根本不用加载它，一旦识别到任务匹配，才把整个模块调进来使用。
1.2 拆开一个 skill，里面到底有什么
一个标准的 skill 目录，通常长这样:
latex-report-helper/ ├── SKILL.md # 入口文件，agent 首先读它 ├── resources/ # 参考资料、模板文件，按需读取 │ ├── latex-template.tex │ └── fonts.conf ├── scripts/ # 可执行脚本，agent 负责调用 │ └── compile.sh └── README.md # 给人看的说明，不是给模型看的SKILL.md 是灵魂，它一般带一段 YAML 格式的元信息，里面最关键的是 name 和 description。description 直接决定这个 skill 什么时候会被触发。body 部分写详细的执行流程、约束条件和注意事项，相当于给模型一本“操作手册”。resources 和 scripts 则负责提供手册之外的实体资产。
我习惯用一个类比来解释：SKILL.md 像一本菜谱，scripts 是厨房里已经接好电的烤箱和厨师机，模型是那个“读菜谱、按步骤操作、随手用工具”的帮厨。它不需要自己发明菜谱，也不需要徒手揉面，它只需要判断“现在该做哪道菜、按哪一页执行”。这也是为什么一个写清楚的 skill，效果往往比十句漂亮的 prompt 更稳。
1.3 边界厘清：skills 和 prompt、插件、MCP、agent 的关系
很多初学者会把 skills 和周边概念混在一起，我先用一张表理清楚：
| 概念 | 本质 | 和 skills 的关系 |
|---|---|---|
| Prompt | 一段即时指令，用完即弃 | skill 里也包含指令，但做了结构化和复用 |
| Plugin | 通常指工具层面的功能集成 | 插件负责接入能力，skill 负责告诉模型怎么用 |
| MCP / 工具调用 | 让 agent 能读写文件、跑命令、调 API | skill 可以指挥模型去调这些工具，两者互补 |
| Agent | 一个能感知、决策、行动的智能体 | skill 是 agent 外挂的“技能专家库” |
| Harness | 承载 agent 运行的宿主框架 | skill 挂载在 harness 上，受它的上下文和权限管理 |
这里单独说说“harness 和 agent 区别”这个高频疑问。我理解的 harness，是那个负责上下文管理、工具调用循环、权限控制的运行环境；agent 是里面做决策的那个“大脑”。skills 不自己跑，它必须被 harness 加载，由 agent 调度。想通这一点，后面排查“skill 没生效”会省很多力气。
2. 生态现状：不同工具里的 skills，各自怎么管
2.1 主流载体一览
现在市面上的 agent 工具基本都开始支持 skills，但各自的目录位置、安装方式和侧重点不太一样。我把自己实际用过的几个整理成表格:
| 工具 | 典型目录 | 安装方式特点 | 我注意到的调性 |
|---|---|---|---|
| Claude Code | ~/.claude/skills/ | 支持插件市场，也能手动 clone 目录 | 生态最成熟，社区例子最多 |
| Codex | ~/.codex/skills/ | 官方明确鼓励 skills，脚本类技能好用 | 和命令行结合紧密 |
| opencode | ~/.config/opencode/skill/ | 开源项目，目录可自定义 | 修改灵活，适合二次开发 |
| pi agent | 桌面端内置技能市场 | 可视化安装，适合新手 | 偏成品应用，封装度高 |
| hermes agent | 仓库内 skills/ 目录 | 跟着项目走，随 agent 一起部署 | 和特定业务流程绑定 |
表格里的路径在不同版本里会有变化，大家以官方文档为准，但这个“约定目录+SKILL.md”的大逻辑是通的。我经常在不同工具间迁移技能，只要把目录调整一下，SKILL.md 基本可以原样复用。
2.2 手动安装一个 GitHub 上的 skills
“Claude Code 怎么手动装 GitHub 上的 skills”是反复被问到的问题。其实就两条路：一是通过插件市场安装，二是我更常用的土办法，直接 clone 到 skills 目录。
以我现在这台机器为例，我想装一个 GitHub 上的 latex 排版技能:
mkdir -p ~/.claude/skills git clone https://github.com/example/latex-report-helper.git ~/.claude/skills/latex-report-helper # 重启对话，然后对 agent 说：“用 latex-report-helper 帮我排一下这篇报告”重启会话很关键，大部分工具只在启动时扫描一次 skills 目录。装好之后，可以先让 agent“列出当前可用的 skills”，确认注册成功，再干活。GitHub 上所谓的“图片生成 skills 安装包”，拆开看也基本是这个结构——一个目录里放着配置脚本、提示词模板和模型参数说明，clone 到约定目录就算“安装包”装好了。
2.3 去哪找高质量的 skills 源
围绕“skills 技能库网址”“常用 skills 源网站”，我总结几个靠谱渠道：
- GitHub 直接搜 awesome-claude-skills、awesome-codex-skills 之类的精选列表；
- 各工具官方文档里的 Use Cases / Plugins / Skills 页，质量最稳；
- 社区热推的 superpower skills，这是一套把项目管理、写作、编程实践整理成技能包的库，我很早就装了，风格是“把资深工作者的思考流程显性化”；
- 关注一些做 agent 开发的人公开分享的 dotfiles 和 skills 仓库。
我的挑选标准是三条：description 写得好不好、最近半年有没有更新、是不是真的解决我重复三次以上的任务。像“ai 漫剧常用 skills”，我看过不少所谓“技能包”，本质就是把“分镜-生图-配音-剪辑”的工作流写成 SKILL.md，再用脚本批量调接口，思路其实和我下面要手搓的例子一模一样。
3. 从零开发一个 LaTeX 排版 skill：完整过程
3.1 先定边界：这个 skill 到底管哪一段
很多人第一次写 skill 就想做一个“万能专家”，上来就是“精通所有排版”，结果 description 含糊，触发率极低，还容易和其他技能抢活。我现在的习惯是先给它划清楚边界。
以“怎么做一个 latex 排版 skills”为例，我先定义这个技能只干三件事：
- 把 Markdown 或零散文本转成中文 LaTeX 文档；
- 编译并修复报错，最终产出 PDF；
- 按固定模板调整标题、字号、行距和代码块样式。
同时明确它不做什么：不负责代写论文内容，不处理 beamer 幻灯片，不优化已有 tex 文件里复杂的自定义宏包。边界写清楚之后，模型才不会在无关场景里乱调它。
3.2 SKILL.md 到底怎么写
这是我的 SKILL.md 实际结构，精简过后如下：
--- name: latex-report-helper description: 当用户要求“排版论文/报告”“生成PDF”“修复LaTeX编译错误”“转换成中文LaTeX文档”时使用。适合中文技术报告、期末论文、数学公式较多的文档。不适用于beamer幻灯片。 --- # latex-report-helper ## 工作流程 1. 判断输入：是已有 .tex 文件，还是需要从 Markdown/零散文本新建。 2. 新建时：读取 resources/latex-template.tex，把正文内容填入对应 section。 3. 图片处理：将本地图片拷贝到 assets/ 目录，改用相对路径引用。 4. 编译：运行 scripts/compile.sh，捕获输出。 5. 如果报错，读取 .log 文件，按 FAQ 里记录的典型错误逐条排查。 ## 格式约束 - 中文字体用 FandolSong，避免依赖系统字体。 - 代码块统一用 lstlisting 环境，等宽字体。 - 数学公式必须用 equation / align 环境，行内公式用 $...$。 ## 注意 - 禁止修改 resources/ 下的模板文件，除非用户明确要求。 - 编译失败时不要反复盲目重试，先看 log。这里最容易被忽略的是 description。它不光是给人看的简介，更是模型的“触发开关”。我见过太多人把 description 写成“一个强大的排版工具”，结果模型根本没在需要的场景联想到它。正确的写法是列出典型任务句，比如“帮我排一下这篇论文”“PDF 编译报错了”“写个中文报告”，再补一句“什么时候不该用它”。这样触发率能提升一大截。
3.3 资源和脚本：真正的功力在目录结构
SKILL.md 写得再好，没有实体资产支撑就是空谈。我的 latex 技能里有几个关键资源文件：
- resources/latex-template.tex：基于 ctexart 文档类的中文模板，预设了标题页、目录、代码块样式、页眉页脚；
- resources/compile.sh：一键编译脚本，我用的是 xelatex + latexmk；
- FAQ.md：把踩过的编译错误和解决方案记下来，模型遇到同类问题直接查。
compile.sh 大概是这样的:
#!/usr/bin/env bash set -euo pipefail cd "$(dirname "$0")/.." latexmk -xelatex -interaction=nonstopmode main.tex脚本一定要设置 set -euo pipefail，不然编译失败的时候 agent 可能拿不到清晰的报错信息。给脚本加执行权限也是一个新手容易漏的操作，我一开始忘了 chmod +x，agent 调用脚本时直接返回 permission denied，排查了半天。
3.4 本地验证：没有 eval 的 skill 都算没写完
技能写完先别宣布完成，跑一遍“验收测试”才靠谱。我每周会往 cases.md 里加测试用例，比如：
- 把一段带公式和代码的 Markdown 排成 PDF；
- 故意留一个“找不到文件”的错误，看 skill 能不能正确修复；
- 给一篇没有标题层级的中文文本，看它能不能自动结构化。
跑的时候我会盯着几件事：技能有没有被正确触发，有没有按 SKILL.md 的流程走，脚本有没有被顺畅调用，final 产物是不是我预期的 PDF。这一轮下来基本能发现一半的描述和步骤问题。Skills 开发的过程不是一次写完，而是“用一次，填一个坑，迭代一版”。
4. 安装、加载与排错：运行时报错与不触发
4.1 加载顺序：为什么改了 skill 却不生效
Skills 的加载机制看似简单，但容易卡在“缓存”上。很多工具的对话会话是常驻的，你往 skills 目录里新增文件之后，当前会话不会自动感知，必须重启会话。团队项目里还有一种情况：项目根目录有自己的 .claude/skills，用户目录也有全局 skills，两个都存在时，项目级优先还是用户级优先，不同工具策略不一样。我踩过的最尴尬一次，是改了半天项目目录里的 SKILL.md，但 agent 实际加载的是全局同名目录。
现在我的操作习惯是：改完 skill 之后，先问一句 agent“你当前能看到的 skills 列表里，latex-report-helper 的 description 是什么”。如果它答出来的还是旧描述，说明加载的路径不对，优先查是不是同名覆盖。
4.2 排查“agent execution terminated due to error.”的完整链路
“agent execution terminated due to error.”这个报错几乎所有 agent 工具都有，可以说是新手劝退第一杀手。遇到它，我现在的排查链条是固定的，也给读者参考：
- 先看调用栈里最后一步是什么工具。如果卡在 script，先手动在终端跑一遍同样的命令，确认是不是环境问题；
- 查技能的脚本有没有执行权限，依赖有没有装上。比如 latexmk 没装，编译脚本必然报错，这时该装依赖而不是改 SKILL.md；
- 看是不是上下文超限。任务太长，agent 的上下文窗口爆了，工具输出会被截断，报错信息最后可能是一半的 JSON；
- 再看是不是“重试死循环”。agent 反复调用同一个失败命令，耗尽一轮工具的调用次数，最终抛出一个笼统的 terminated error。这种时候不要盲目加提示词，要解决根因，比如给脚本加超时、加错误处理；
- 最后才考虑是不是 skill 自身的指令和当前工具版本不兼容。比如 API 参数变了、命令别名不存在。
按照这个顺序排查，大部分问题都能在十分钟内定位。千万不要一看到报错就去搜“如何让 agent 不报错”，那只会把问题压得更深。
4.3 你的 skill 为什么从不被触发：description 的匹配误区
“为什么我装了一堆 skills，agent 一次都没用过”，这是我收到最多的问题。大多数原因都出在 description 的写法上。
我归纳了三种典型误区：
- 太短：description 只写“处理图片”，模型在遇到“把这张图背景换成白色”时根本联系不上；正确写法是“处理图片透明背景、尺寸调整、圆角裁剪、格式转换，当用户提到 png/jpg/webp 或图片尺寸时使用”。
- 太长：description 写了一整段小作文，模型在有限选择空间里根本读不完；正确写法是控制在三到五句话，前面是触发词，后面是排除条件。
- 全是名词、没有动词指令：只写“LaTeX、论文、PDF”，但用户说“帮我排一下”的时候，模型无法匹配意图；正确写法是既包含名词也包含典型任务句。
我还发现一个细节：skill 的 name 不要取太通用，比如“latex”“report”这种，容易和其他技能的 name 冲突。社区习惯用小写中划线加后缀，比如 latex-report-helper。命名清晰了，模型在判断多个候选技能时也能更准确。
4.4 上下文膨胀：为什么我没让你疯狂堆技能
很多新手会走入“skills 越多越好”的误区，这也是社区里讨论“tibo 关于清理 skills 的方法推荐”时的核心话题。我亲测的感受是：每多挂一个 skill，都会多占系统提示词的长度，模型在每次工具调用时也需要多考虑一层“要不要触发它”。技能库装到二十个以上，未必更聪明，反而可能更迟钝。
我自己的清理原则非常简单：每个季度看一遍所有 skill 的调用日志，凡是三个月内一次都没被触发过的，直接归档到不用目录；凡是触发过但频繁出错的，回到章节 3 的流程重写。社区里那位很活跃的 Claude Code 专家 tibo 分享过类似态度：他认为技能库要保持“最小可持续”的状态，删掉反而是一种能力提升。这几年实践下来，我完全同意这个判断。省出来的上下文和选择空间，应该留给真正高价值的技能。
5. 从个人技能到团队资产：管理、评估与护栏
5.1 目录治理：让技能可以交给别人维护
当 skills 从“自己写着玩”变成“团队协作资产”时，目录治理必须跟上。我现在会在每个 skill 里加一个 README 和 CHANGELOG，前者写给人，后者记录改动。版本号我有自己的规则：SKILL.md 结构大改或者脚本接口变了，升主版本；只是修了 description 或补了 FAQ，升次版本。
目录命名和拆分的纪律也要统一。一个 skill 里面不要混合多个不相关能力，比如“排版 + 数据分析”这种就拆成两个。拆开之后，模型按任务选择触发，互不干扰；人维护的时候，改动范围也清晰得多。
5.2 清理方法论：宁缺毋滥和“按项目配技能”
给团队建技能库的时候，我强烈建议按项目维度分目录，而不是所有人共用一个巨大的全局技能库。比赛项目就放建模论文相关技能，内容生产项目就放分镜脚本和风格提示词技能，每个项目只挂载自己需要的那几个。
这样做的逻辑很朴素：代理工具的上下文是稀缺资源，技能之间还会互相干扰。比如同时装了“latex-report-helper”和“markdown-to-epub”，用户说“帮我排一下”的时候，模型就要纠结到底用哪个。按项目配置之后，选择空间变小，触发准确率自然提高。这个思路和上一节说的清理方法论一脉相承：不是“我有什么技能都塞进去”，而是“这个任务需要哪个技能，就只暴露哪些”。
5.3 用 agent evals 让 skill 表现可度量
光靠“感觉变聪明了”是不够的，想长期迭代，必须搭一套轻量级的 eval。我自己搭过最简单的验证集：每个 skill 配 10 到 20 条典型请求，每次改动后把请求全部跑一遍，再对输出做打分。
打分的维度我固定为三类：
- 触发准确率：该触发的时候有没有触发，不该触发的时候有没有误触发；
- 产物完整度：有没有按 SKILL.md 的流程走到最后，产物有没有缺失；
- 脚本执行成功率：编译、调用这类动作是否一次通过。
以前端写代码时的直觉来类比，skills 就是“测试用例驱动的开发”。没有 eval 的技能，就像没有测试的代码，今天能用，明天你可能都不知道它什么时候坏的。我现在每次改完 SKILL.md，都会跑一遍最小验证集，跑过再提交，跑不过就继续调。
5.4 agent 安全：给技能脚本加上护栏
聊到最后，必须提一个更严肃的话题：agent 安全。Skills 天生自带脚本执行能力，这既是它强大之处，也是风险所在。一个来源不明的 skill，理论上可以在你机器上跑任何命令。我自己在网上逛到的所谓“技能安装包”，偶尔会发现脚本里夹着 curl 外传目录结构的可疑行为。
我的安全底线有几条，也分享给读者参考：
- 只装可信来源的 skill，GitHub 仓库要先扫一遍脚本，尤其注意 scripts 目录和 .sh 文件；
- 给 skill 目录设置只读权限，非必要不让 agent 改 SKILL.md；
- 在 SKILL.md 里显式声明“禁止执行 rm -rf、禁止下载并运行远程脚本、禁止访问 .env 文件”；
- 定期审计技能库的 git diff，发现异常改动立刻回滚。
还有一个软性约束：agent 执行会改变系统状态的命令前，应该先输出计划让用户确认。这个习惯可以在 SKILL.md 里写成流程步骤，相当于给模型加了一层“人工确认闸门”。
最后说几句我的真实感受
我从一开始见到“skills”这个概念就挺兴奋，但真正把它用好，靠的不是堆数量，而是对“模型怎么触发、怎么执行、怎么验证”的完整理解。这几年最值的一条经验是：第一个 skill，应该从你重复过三次以上的任务开始写，不要一上来就想做一个包罗万象的大全。写完以后用日志跟踪它，用 eval 验证它，用清理机制淘汰它。技能库会从一个“玩具”慢慢长成真正属于你的工作流基础设施。这条路不需要多强的编程功底，需要的是耐心和复盘习惯。等你也写出第一个自己天天在用的 skill，大概就能理解我为什么说“agent 的差距，很大程度是 skills 的差距”。
