做 AI Agent 开发这大半年我踩得最深的坑不在模型选型也不在框架配置而在 skills。这个词如今被说得很多——GitHub 上随手一搜就是几百个 skill 仓库社区里三天两头冒出“superpower skills”“AI 漫剧常用 skills”这类热词但真正能讲清楚 skills 是什么、怎么写、怎么装、怎么排障的人其实很少。我一度以为 skill 就是“给 agent 写一段提示词”直到亲手做了 agent-skills 这个项目把几十个技能装进 Claude Code、Codex、Pi Agent 这些环境里反复跑才把这里面的门道彻底摸透。这篇文章是我实际做 agent-skills 相关项目过程中的完整复盘。它不是什么官方文档翻译也不是概念科普而是从“我要给 agent 装一组能稳定复用的技能包”这个真实需求出发把 skill 和 agent 的边界、SKILL.md 的写法、Claude Code / Codex 手动安装流程、常见报错的排查套路以及 LaTeX 排版和图片生成这类实战 skill 的落地过程全部摊开来讲。适合正在做 agent 开发、或者刚接触 Claude Code / Codex / Pi Agent 这类工具、想给智能体补齐专业能力的读者。1. 先搞明白Agent Skills 到底是什么1.1 skill、agent、harness 三者的边界很多人一开始都会被这三个词绕晕。我自己的理解是agent 是一个“能思考、能决策、能调用工具”的执行者它负责接收任务、拆解步骤、调用工具、汇总结果harness 是 agent 运行时的外部约束层它决定了模型能访问哪些工具、哪些文件、哪些权限相当于给 agent 划了一条活动边界而 skill 是装进 agent 手里的“专业技能包”里面包含一段写好的操作指南、配套脚本、模板文件让 agent 在遇到特定任务时不用从零摸索直接按成熟流程执行。打个比方agent 是一个新入职的员工harness 是公司的规章制度和门禁权限skill 则是老员工整理好的“岗位操作手册工具包”。员工再聪明没有操作手册也容易凭感觉做事制度再完善不教具体怎么做也产出不了高质量结果。所以三者是互补关系harness 管“能做什么、不能做什么”skill 管“这件事具体怎么做才专业”。网上常有人问“skill 和 agent 有什么区别”其实它们根本不是同一层的东西。skill 是给 agent 用的插件包agent 是承载 skill 运行的主体。同一个 skill 可以被不同的 agent 加载比如一个 PDF 解析 skill既能给 Claude Code 用也能给 Codex 用只要它们遵循相同的 skill 加载约定。我在项目里就经常把同一个技能在两个工具间来回搬这份通用性正是 skills 模式的魅力所在。1.2 为什么 agent 开发绕不开 skills大概从去年开始我明显感觉到纯靠提示词去驱动 agent 已经不够了。原因很简单大模型的上下文窗口再大也不可能把所有专业流程都塞进一条 prompt 里而且提示词是“一次性的”每次任务都要重新写、重新调很难沉淀成资产。skills 这个模式解决了三个非常实际的问题。第一是知识外置把某个领域的操作流程、注意事项、模板文件全部打包进 skillagent 只在需要时读取不占用日常对话的上下文空间。第二是可复用一个写好的 skill 可以跨项目、跨 agent 使用团队里共享一份大家产出的行为就一致了。第三是可迭代skill 就是普通文件放进 Git 就能版本管理改坏了随时回滚。我做过一个对比实验同一个 agent没装 skill 时让它做一个 LaTeX 排版任务它会把排版格式做得乱七八糟装上一个写好的 skill 之后同样的任务输出质量几乎稳定在同一个水平线上。这就是“手艺”和“套路”的区别。agent 不缺智商缺的是一个靠谱的套路而 skills 就是把这些套路沉淀下来的标准方式。2. Skills 开发的关键细节从最小结构到完整规范2.1 一个 skill 的最小文件结构很多人以为 skill 很神秘其实剥开看就是一组普通文件通常长这样my-skill/ ├── SKILL.md # 核心指令文件agent 最先读的就是它 ├── scripts/ # 辅助脚本比如 Python / Shell 脚本 ├── assets/ # 模板、参考图片、数据文件 └── requirements.txt # 依赖清单可选整个 skill 里最关键的只有 SKILL.md。这个文件的命名和放置路径都有约定Claude Code 要求每个 skill 独立占一个目录目录里必须包含 SKILL.md目录整体放在个人级或项目级的 skills 文件夹下Codex 的约定大同小异只是具体路径不同。很多新手在这里栽跟头把 SKILL.md 直接丢在 skills 根目录下面没有单独建子目录结果框架扫描时根本不认这个技能。我建议一开始不要贪多一个小 skill 只要两样东西就能跑一个写清楚的 SKILL.md外加一个可选脚本。等跑通了再逐步加 assets 和依赖清单。先用最小的结构把流程走通比一开始就设计一个庞大的目录树要实在得多。2.2 SKILL.md 到底该怎么写这是 skill 开发里最关键、也最容易被低估的一步。我的经验是SKILL.md 不是写给人类看的说明文档而是写给“一个很聪明、但对你的领域完全不了解的实习生”看的操作手册。你是在把老师傅脑子里的经验翻译成文字翻译得越具体agent 执行得越稳。一个好的 SKILL.md 至少要包含这几块内容概述说明这个 skill 是干什么的、在什么场景下使用适用与不适用情况明确写出什么时候该用、什么时候不该用避免 agent 误调用操作步骤按顺序列出完整的工作流每一步要具体到可执行质量标准告诉 agent 什么样的输出算合格比如格式要求、检查清单反模式列出常见错误做法并提醒 agent 规避还有示例给一两个输入输出样例让 agent 有参照。举一个我在 LaTeX 排版 skill 里写过的例子。我不会只写“帮用户排版论文”而是会写清楚优先使用哪些文档类、中文场景用哪个宏包、图表用哪个环境、参考文献用哪种格式、编译报错时先检查哪几个地方。这样 agent 拿到任务时每一步都有据可依而不是凭训练数据里的模糊记忆瞎猜。还有一个细节SKILL.md 开头一定要有清晰的元信息比如 name 和 description。description 尤其重要因为 agent 是靠它来判断“这个任务该不该调用这个 skill”的。描述写得太泛agent 会乱调用写得太窄该调的时候又调不到。我常用的技巧是描述里同时包含“触发场景”和“不使用场景”把边界划清楚让 agent 的选择成本降到最低。2.3 三类最常见 skill 的写法差异我拆过不少社区里的 skill发现它们大致分成三类写法侧重点完全不同。第一类是流程编排型比如代码审查、数据清洗、自动化测试。这类 skill 的核心是步骤编排把一系列工具调用串成流水线写的时候要把每一步的输入输出和判断条件写清楚重点是“流程不漏步、异常有兜底”。第二类是专业领域型比如论文排版、财务分析、法律文书。这类 skill 的核心是领域知识外置把术语、规范、模板都收进来写的时候要重点写“质量标准”和“反模式”因为领域任务最怕 agent 凭常识瞎发挥。第三类是工具封装型比如调用某个 API、操作某个软件。这类 skill 的核心是脚本SKILL.md 反而可以精简重点是教会 agent 怎么传参、怎么处理返回值、怎么识别报错。搞清楚自己写的是哪一类写起来就快很多。我自己一开始就犯过错误想写一个全能型的“超级 skill”塞了一堆互不相关的内容结果 agent 每次调用都不知道该执行哪一部分效果反而不如几个小而精的 skill。后来我把这个大而全的东西拆成三个独立技能整体成功率直接上了一个台阶。3. Skills 的安装、推荐与日常管理3.1 Claude Code 和 Codex 手动安装 skills社区里问得最多的问题就是“Claude Code 怎么手动装 GitHub 上的 skills”。其实流程非常简单先把 GitHub 上的 skill 仓库 clone 到本地然后确认仓库里的目录结构中有 SKILL.md再把整个技能目录复制到 Claude Code 的 skills 路径下个人级是~/.claude/skills/项目级是.claude/skills/最后重启 Claude Code 或者用相关命令刷新技能列表。Codex 的安装逻辑类似只是路径换成~/.codex/skills/或项目目录下的.codex/skills/。装完可以用一条简单的测试指令验证比如直接对 agent 说“列出你当前可用的 skills”看它能不能正确识别到新装入的技能。这一步千万别省很多安装失败都是因为路径放错但当时完全没发现。这里有个容易踩的坑不少 GitHub 仓库是“skill 集合”一个仓库里包含十几个甚至几十个技能目录。这时候不要整个仓库复制进去应该按需把需要的子目录单独复制到 skills 路径下。装得太多agent 在工具选择阶段会变慢还容易选错最后反而拖累整体效率。3.2 常用 skills 源网站和推荐清单现在 skills 的获取渠道已经比较成熟了。GitHub 上有不少高质量的技能集合仓库比如 Anthropic 官方维护的 skills 示例库里面包含 LaTeX 排版、数据可视化、PDF 处理、量化分析等常用技能。社区里也有各种 awesome 风格的列表把大量按场景分类的社区 skills 整理成了目录找起来很方便。我在实际项目中常用的几类 skills 大概是这样的使用场景推荐 skill 方向说明文档处理LaTeX 排版、PDF 解析、Markdown 转格式论文、报告场景刚需前端开发组件生成、样式检查、页面还原配合编辑器类 agent 效率提升明显内容创作AI 漫剧分镜脚本、图片生成提示词画风统一、分镜稳定的关键数据工作数据分析、SQL 生成、图表绘制适合建模竞赛和日常报表搜索技巧方面我习惯用“site:github.com 加上场景关键词”的方式去找命中率比直接搜 skills 高得多。另外还要提醒一句从任意渠道下载 skill第一件事是通读 SKILL.md 和 scripts 里的代码确认没有可疑命令再安装。现在 agent 的权限越来越强一个恶意的 skill 可能诱导 agent 执行危险操作安全这根弦不能松。本地 skills 装多了之后想快速查某个技能里写了什么也可以用 Agent Ransack 这类本地全文搜索工具直接扫 skills 目录比一个个文件夹翻要快得多。3.3 Skills 的清理与版本管理skills 装多了之后麻烦就来了。我见过有同事一台机器上装了四十多个技能结果 agent 每次做任务都要在几十个选项里做选择经常选错整体效率反而断崖式下降。社区里有人专门讨论过清理 skills 的方法我实践下来最有效的是三条。第一定期审视使用频率一个月没被调用过的技能直接禁用不要心疼。第二按项目隔离把通用的轻量技能放在个人级目录把项目专属的技能放在项目级目录避免互相干扰。第三维护一个“白名单”新下载的 skill 先放进临时目录试用确认稳定后再转正到正式目录从源头控制技能总量。版本管理方面我强烈建议把团队的 skills 目录做成一个 Git 仓库。每次改动都留记录谁改了什么一目了然。技能迭代和代码迭代其实是一样的一定是边用边改没有版本记录就只能靠记忆迟早出问题。我现在每次跑完一个失败案例第一件事就是在 skill 的文档里追加一条注意事项并提交几个月下来这些技能变得非常抗造。4. Agent 开发学习路线框架、编排、记忆与评估4.1 主流开源 Agent 框架速览如果你想系统学习 agent 开发而不是只停留在“给 agent 装个 skill”的层面那一定绕不开框架选型。目前社区里活跃度比较高的几个方向包括Pi Agent主打桌面端和浏览器自动化适合做“能自己操作电脑干活”的智能体有官方桌面应用对普通用户比较友好Hermes Agent定位本地优先的通用 agent强调隐私和可扩展性社区讨论很多安装方式也比较简单OpenCode开源终端里的编程 agent主打和编辑器、命令行深度集成适合开发者日常使用再就是 Claude Code、Codex、Cursor 这类商业或半商用工具内置了 agent 能力也是我日常用得最多的执行环境。学习路线我的建议是先从商业工具上手因为门槛最低能快速感受到 agent 加 skills 的完整闭环然后选一个开源框架读源码重点理解它的“工具调用循环”是怎么实现的也就是模型怎么决定调哪个工具、工具返回后怎么继续推进最后再动手写一个极简框架把控制循环、上下文管理、错误处理各写一遍你会对 harness 和 agent 的关系有非常直观的理解。这条路线走完再去看社区里那些新框架基本一眼就能看出它的设计取舍。4.2 框架与编排理解 harness 和 agent 的分工前面提到了 harness 和 agent 的区别这里展开说一下。框架层面的代码通常分成两层外层是 harness负责安全策略、工具注册、权限控制、会话管理内层是 agent负责任务规划、调用决策、结果反思。为什么需要这种分工因为纯让模型自己决定“能调什么工具”是很危险的没有 harness 约束一个模型可能因为某句 prompt 就尝试读取敏感文件、执行危险命令。harness 相当于在模型和系统之间加了一道闸门所有工具调用都必须经过它审批才能放行。理解了这一层你就明白为什么 skills 要放在 harness 能管理的目录里skill 本质上也是一种“被批准的工具包”harness 扫描目录、加载元信息、注册成可用工具agent 才能在运行时发现它。所以当你发现“skill 装上了但 agent 看不到”大概率是 harness 的加载路径或者文件格式出了问题而不是模型的问题。我见过很多初学者把精力全花在调提示词上却忽略了对 harness 层的理解。其实只要把工具注册、权限配置、上下文管理这几个机制搞明白很多看似玄学的问题都能迎刃而解。框架和编排的价值就在这里它决定了你的 agent 是“裸奔”还是“穿着装备作战”。4.3 记忆、评估与安全把 skill 放对位置除开技能一个完整的 agent 还涉及三个容易被忽略的组件记忆、评估、安全。记忆解决的是跨会话连续性问题最简单的实现是把历史关键信息写成结构化文件存起来复杂一点会用向量数据库做语义检索。我的经验是能用文件解决的场景不要急着上向量库文件直观、可控、好调试很多 agent 需求其实用不上语义检索。评估解决的是“怎么知道 agent 改好了还是改坏了”的问题。我强烈建议每个项目至少维护十条以上的评测用例覆盖典型任务和边界情况。每次修改 skill、提示词或者框架配置都跑一遍评测看成功率是上升还是下降而不是凭感觉判断。社区里常说的 evals 就是这个意思它本质上是在给 agent 做单元测试。安全则贯穿始终。除了前面说的检查 skill 内容还要注意三点给 agent 的权限遵循最小化原则能不给的权限尽量不给对来自外部的文件或链接要求 agent 先检查再处理防止提示词注入敏感操作设置人工确认环节避免 agent 在无人监督时执行高风险动作。在我自己跑项目的过程中安全配置做得越细反而越敢放权给 agent 去做复杂任务因为你知道它不会越界。5. 从报错到可用常见问题排查实录5.1 “agent execution terminated due to error” 排查思路“agent execution terminated due to error”是社区里被问得最多的一条报错。这个提示本身只说“执行被终止”真正的原因千奇百怪。我排查这类问题的固定顺序是四步。第一步看上下文长度很多 agent 在执行长任务时把中间过程全部堆在上下文里一旦超限就会被强制终止解决办法是拆分任务、减少不必要的中转输出或者给 agent 配置摘要机制。第二步看工具调用格式agent 生成的动作如果不符合工具协议框架会直接终止这时要检查是不是自定义 skill 的参数格式写错了比如 JSON 字段名不一致。第三步看外部 API 错误模型服务限流、超时、返回异常都会导致中断这类错误通常会在日志里给出更具体的提示优先看日志尾部。第四步看权限问题agent 尝试访问没有权限的文件或命令被 harness 拦下来也会呈现为 terminated。我的经验是遇到这类错误先不要慌把日志级别调成 debug 重跑一遍百分之九十的原因都会在日志里现出原形。基本没有必须靠猜才能解决的问题。把这条报错当成一个“总入口”顺着日志往里钻比反复重试有效得多。5.2 Skill 装上了却不生效怎么办这个问题的出现频率也很高。装好 skill 之后agent 完全不调用它或者调用了但行为没变化。我排查时会按下面的顺序一项项过。首先确认路径是否正确skills 该放在个人目录还是项目目录不同工具有不同约定放错位置就白装了。其次确认元信息是否规范SKILL.md 里的 name 和 description 有没有写清楚description 写得不好agent 在决策时根本不会选中它。然后确认目录是否完整有些 skill 依赖 scripts 下的脚本文件复制的时候漏了文件skill 一运行就报错。最后确认是否刷新部分工具需要重启会话才能重新扫描技能目录装完没重启自然看不到效果这不是 skill 的问题是你没给它“上岗”的机会。另外还有一个很容易被忽略的点项目级目录的技能优先级通常高于个人级目录。如果你在个人级装了一个旧版本、项目级又放了一个新版本agent 很可能会加载旧的那个排查时记得把两个目录都看一眼。5.3 工具调用混乱与上下文污染装了一堆 skills 之后另一个典型问题是 agent 频繁调用错误的技能或者一次任务把所有技能都“过”了一遍。这通常是两个原因造成的一是技能描述写得太宽泛导致多个技能在 agent 看来都“沾边”选择困难二是技能数量过多工具选择空间太大模型决策难度直线上升。对应的解决办法也很直接把各个技能的 description 重新精修明确各自的触发边界让相似技能之间形成互补而不是重叠同时对暂时用不上的技能禁用让可选集变小。上下文污染的问题则要靠“减少中转输出”来解决让 agent 只保留对后续步骤有价值的信息而不是把工具的所有原始输出都留在上下文里。我习惯在 SKILL.md 里明确写一句“只返回摘要不要粘贴完整日志”这一个习惯就能省下大量上下文空间。6. 两个实战案例LaTeX 排版 skill 与 AI 漫剧图片生成 skill6.1 从零开发一个 LaTeX 排版 skill完整走一遍写 skill 的流程我拿 LaTeX 排版来做例子。这个需求很典型很多用户并不熟悉 LaTeX但写论文、做报告、排简历都需要它符合“专业性高、流程固定、经验可沉淀”的 skill 特征。我的 SKILL.md 结构大概是这样的--- name: latex-typesetting description: 用于 LaTeX 文档排版包括论文、报告、简历。当用户需要生成或修改 .tex 文件时使用不用于纯文本排版。 --- # LaTeX 排版 ## 使用前提 - 确认输出目标是 .tex 文件且编译引擎可用。 ## 排版步骤 1. 根据文档类型选择文档类article/report/ctexart。 2. 正文用结构化写法图表用 figure/table 环境。 3. 参考文献用 BibTeX编译顺序按 xelatex - bibtex - xelatex - xelatex。 ## 质量标准 - 中文字符能正常编译。 - 图表编号和引用一致。 - 不出现 Missing $ 和 Undefined control sequence 类报错。 ## 反模式 - 不要手工调整页码和边距来硬排版。 - 不要混用不同宏包的相似功能。核心思路是把一个专业排版人员的经验全部压进文件里。我还会附一个模板文档放到 assets 目录agent 可以直接复制改。这个 skill 开发完成后实测效果提升非常明显原本 agent 生成的 LaTeX 经常编译不过装上后出错率大幅下降因为反模式部分已经提前把最常见的坑写明白了。这个案例对我最大的启发是写好一个 skill 的关键不是堆功能而是把你踩过的坑全部写进去。6.2 安装并调优一个图片生成 skill另一个高频场景是 AI 漫剧的图片生成。这类任务的痛点是画风不稳定、分镜不统一社区里有一些现成的图片生成 skills 安装包装好后能给 agent 提供结构化的提示词模板让每次生成的画面风格都锁定在同一套参数里。安装流程和前面说的一样下载、放进 skills 目录、重启、验证。但真正值钱的是调优环节。我会重点修改 skill 里的提示词模板把角色描述、场景描述、光线风格固定成若干可替换的插槽每次生成时只替换关键变量。这样即便换了场景画风和角色形象也能保持一致。这个思路其实和写代码是一样的把不变的东西抽象出来把变化的东西做成参数图片生成 skill 立刻就从“能用”变成了“好用”。6.3 前端开发类 skills 的选型经验最后简单说下前端开发场景。热词里提到的 superpower skills其实是社区里一套比较知名的技能集合里面覆盖了前端组件生成、代码审查等常见任务。我的建议是不要整套安装按需选几个和你技术栈匹配的单独用。前端类 skill 的选型核心看两点一是它使用的技术栈版本是否和你项目一致二是它有没有内置质量检查步骤。一个只生成代码但不做检查的 skill产出的代码往往需要大量人工返工而包含 lint 和构建验证步骤的 skill才是真正能减少工作量的。我自己选 skill 的标准很简单先看它的 SKILL.md 里有没有“验证”部分没有的坚决不装因为那只是把不完整的活推给你自己。我个人在实际操作中最大的体会是agent 的能力上限由模型决定但它的能力下限由 skills 决定。同样是当前主流的模型装没装好一组高质量 skills实际交付质量可以差出好几个档次。所以如果你现在正准备入门 agent 开发我的建议是别急着追新框架先手写两三个自己的 skill把 SKILL.md 写好、装进工具、跑通一个完整任务再回头看框架源码整个认知会瞬间打通。最后再分享一个小技巧给你的每个 skill 都建一个“失败记录”。每次 agent 在某个步骤上出错就把错误现象和修复方法追加进去并在 SKILL.md 的反模式里同步更新。跑几个月之后这个 skill 会变得非常抗造这才是 skills 最大的复利效应。
