从“能聊”到“能干”：Agent Skills 实战指南与踩坑总结

写这篇东西的起因是我最近连续被几个做 agent 开发的朋友问到同一个问题模型已经这么强了为什么我搭出来的 agent 还是嘴上厉害、手上拉胯问的人多了我意识到agent-skills这个词已经被炒得很热但大多数人对它的理解还停留在给模型加一段 prompt的层面。实际上skills 解决的是 agent 从能聊到能干之间那段最关键的差距。这篇文章我会把 skills 是什么、怎么装、怎么挑、怎么自己写、怎么评测和防翻车一次性讲透。内容主要面向正在做 agent 项目、想给 Claude Code 或 Codex 等工具加装技能、以及准备系统学习 agent 开发路线的读者。文章里的路径和方案都以本地实践过的为主不是抄文档是我自己踩过坑之后的结论。1. 从能聊到能干Skills 到底解决了什么问题1.1 模型会说话但不一定会干活先讲一个让我印象特别深的对比。同样让一个 agent 做把一张数据表转成折线图这个任务我把需求直接写进 system prompt 让它自由发挥和给它挂一个提前写好的 chart skill 再让它干活结果完全不一样。只靠 system prompt 的时候模型通常会这么走先按自己印象写一段 matplotlib 代码试着跑一下报错再修再跑如果运气不好遇到中文字体问题、数据格式问题、坐标轴刻度问题它能来回折腾七八轮。这还算好的更麻烦的是它每次生成的代码风格都不太一样同样的任务换一天再问输出就变了。作为开发者的我根本没办法对它的行为做任何预期管理。挂上 skill 之后agent 的行为完全变了。它会先读 skill 里的操作规范按里面写好的模板走——数据清洗用什么方式、图表配色用哪套、中文字体怎么处理、图片输出到什么路径全部是预设好的。我实测下来同样一个任务没挂 skill 之前平均要 6 到 10 轮工具调用挂了之后 2 到 3 轮就能出结果。这就是 skills 最核心的价值它把模型应该知道但可能不知道的领域操作流程从模型的长期记忆里搬出来放到一个可以被明确引用的外部文件里。模型不再需要靠猜来完成专业任务而是靠查来按规范执行。一句话总结就是——skills 是给 agent 的肌肉记忆不是给它的新知识。1.2 Skills、Tools、Agent 三者的边界很多刚开始接触 agent 开发的人最容易把 skills 和 tools 搞混这俩名字听着像但层级完全不同。我的理解是这样的Tools是 agent 可以直接调用的函数或 API比如搜索网页、读写文件、执行 shell 命令。它解决的是模型能不能碰到外部世界的问题。颗粒度非常小一次调用干一件事。Skills是一套操作手册 执行模板它可能包含多个步骤、会组合多个 tools、还附带领域知识和最佳实践。它解决的是模型知不知道该怎么按规范干活的问题。颗粒度很大一个 skill 覆盖一类任务。Agent是完整的执行体有上下文记忆、有计划能力、有工具调用循环。它解决的是谁来拆解任务、决定调什么、怎么调的问题。一个 agent 可以同时挂载多个 skills也可以按需装卸。我用一个生活化的类比来解释tools 是工具箱里的锤子、螺丝刀、电钻skills 是每件工具的使用说明书 老师傅经验手册比如怎么在 20 分钟内完成一把椅子的组装而 agent 是那个看懂了图纸、决定用什么工具、按什么顺序操作的木工师傅。这个区分不是抠概念它直接决定了你的项目怎么落地。如果你只是给 agent 加了一堆 tools但没做 skills那模型就像把工具箱扔给了从来没干过活的人它知道每个工具是干嘛的但不知道什么时候该用、怎么搭配用。而 skills 的价值就是那个老师傅的隐性经验被显性化了。1.3 Harness 与 Agent跑在什么壳里决定了 Skills 怎么生根搜索热词里有个harness 和 agent 区别这俩概念看起来拗口但在 skills 这事儿上恰恰绕不开。按照 community 里比较公认的说法harness 是 agent 的运行时外壳它负责管理上下文窗口、处理工具调用的循环、执行环境的安全策略agent 是跑在这个壳里的大脑它做规划、做决策、决定下一步调用什么。我给你一个更直白的理解harness 是操作系统agent 是运行在操作系统上的应用程序。操作系统负责分配内存、管理文件系统、提供网络协议应用程序只管实现自己的业务逻辑。没有操作系统应用程序跑不起来没有 harnessagent 的所有推理和工具调用都缺少载体。这对 skills 意味着什么skills 的加载、触发、执行完全是 harness 层面的机制。比如 Claude Code 的 harness 会在每次对话时扫描 skills 目录把匹配的技能动态注入上下文Codex CLI 的 harness 也有自己的一套 skills 解析逻辑。你要写一个 skill首先得知道你目标平台的 harness 是怎么解析它的。所以后面我讲安装和开发的实操一定会绑定到具体平台因为脱离 harness 谈 skill 就是纸上谈兵。2. 主流运行载体与安装实操从 Claude Code 到 Codex 再到本地框架2.1 Claude Code Skills 的目录结构与安装步骤Claude Code 是目前我用下来对 skills 支持最完整的一个 agent 开发工具。它的 skill 机制我在本地跑通了 n 次先说结论看懂目录结构安装就成功了一半。Claude Code 的技能目录有两个层级用户级目录~/.claude/skills/所有项目都能用适合放通用技能。项目级目录项目根目录/.claude/skills/只有当前项目能用适合放跟业务强相关的技能。每个 skill 是一个独立文件夹文件夹里必须有一个SKILL.md作为入口文件。一个典型的 skill 结构长这样~/.claude/skills/ └── chart-helper/ ├── SKILL.md ├── assets/ │ └── template.py └── scripts/ └── validate_data.pySKILL.md是 harness 读取的核心它包含两大部分YAML frontmatter 和正文。frontmatter 里最关键的是name和description这两个字段决定了模型什么时候会触发这个技能。description 写得越具体、越贴合实际任务场景模型的触发准确率越高。我在 4.1 节会专门讲这块怎么写这里先不展开。安装的本质其实就是把这个文件夹放到对应目录下。官方推荐的命令是# 安装到用户级目录所有项目可用 mkdir -p ~/.claude/skills/my-skill cp -r /path/to/my-skill/* ~/.claude/skills/my-skill/ # 检查目录结构是否正确 find ~/.claude/skills -maxdepth 2 -type f放好之后不需要重启新开一个 Claude Code 会话就能自动扫描到。如果你想立刻验证某个技能有没有被加载可以直接在会话里问它你有哪些可用的技能它会列出已经加载的列表。这个验证习惯很重要我见过很多人装了半天最后发现是路径放错了。2.2 Codex Skills 的安装方式与差异点OpenAI 的 Codex CLI 现在也支持 skills跟 Claude Code 在理念上相似但细节上有几个差别值得注意。首先是目录不同。Codex 的 skills 放在.codex/skills/目录下同样区分用户级和项目级。用户级目录一般在~/.codex/skills/项目级就在你工作目录下建.codex/skills/。其次是SKILL.md的 frontmatter 字段不完全一样。Codex 更强调description中的何时使用/何时不使用约束因为它在触发机制上更依赖语义匹配。我实际测试下来Codex 对 description 里负面约束的敏感度比 Claude Code 高——比如你在 description 里写不要用于简单的文件读写任务它在需要简单读写时确实更不容易误触发。安装命令跟前面差不多# 项目级安装进到项目根目录执行 mkdir -p .codex/skills cp -r /path/to/my-skill .codex/skills/ # 验证 ls -la .codex/skills/my-skill/SKILL.md还有一个容易被忽略的点Codex 对 skill 文件夹命名要求是snake_case小写下划线不能用空格和大写字母否则解析阶段会直接跳过。Claude Code 对命名相对宽松但我还是建议统一用snake_case跨平台复用时不用改名字。2.3 本地优先的 opencode、hermes agent 与 pi agent除了 Claude Code 和 Codex最近 opencode、hermes agent、pi agent 这几个项目在社区里讨论热度很高。它们都属于本地优先的 agent 框架特点是可以接自己的模型 API数据不出本机而且都开始原生支持 skills 机制。以 opencode 为例它的 skills 目录设计成了插件机制支持从 Git 仓库直接拉取技能相当于一个技能包管理器# opencode 安装社区技能的示例 opencode skill install author/awesome-skill我没有把它当主力工具但确实给几个测试项目用过。说实话这些新框架的 skills 生态还处于早期阶段最大的问题不是功能缺失而是可用技能的存量太少社区里真正经过验证的技能包数量跟 Claude Code 生态相比差距很明显。它们的优势在于开放性和可定制性适合你愿意自己动手写技能、而不是纯粹消费社区技能的开发者。我的建议是日常做 agent 开发主力还是 Claude Code 和 Codex它们现在的 harness 稳定性足够skills 的解析、触发、上下文注入都有成熟的实现opencode 这类可以作为实验田试一些新玩法比如技能的热更新、技能之间的依赖关系。等它们的生态追上来再考虑迁移也不迟。3. 社区里值得装进 Agent 的 Skills 清单与筛选标准3.1 前端开发与代码方向最实用的莫过于规范即技能先说不装白不装的一类——前端开发类 skills。严格讲前端开发技能不是让模型会自动写 React/Vue而是把团队规范、可访问性要求、常见性能优化项预置成标准流程。比如我常用的一个前端技能它规定了组件文件怎么拆分、样式方案用哪个、SSR 和静态生成的取舍逻辑、图片资源如何走 CDN、mock 数据怎么组织。模型一旦加载这个技能生成的代码从一开始就符合团队规范省掉大量 review 时的返工。还有一类代码方向技能越来越流行——legacy modernizer旧代码现代化。这词在热词里出现了实话说这是我觉得最实用的一类技能。它做的事情是定义怎么把老代码安全升级的流程先扫描项目现状、列出依赖版本、识别废弃 API、生成升级路径、逐步替换并在每步后运行测试。没有这类技能时模型遇到 legacy 代码基本靠猜有了技能它就会按照预设的先体检、后微创、再复查的流程走大幅降低大改伤筋动骨的风险。3.2 结构图、图片生成、LaTeX 排版这类输出型技能第二类值得安装的是输出型技能也就是把某种特定格式的输出标准化。热词里出现了结构图 skills、图片生成 skills 安装包、LaTeX 排版 skills我逐个说。结构图技能我强烈推荐装一个它的典型作用是让 agent 从一段描述里自动输出 mermaid 或 drawio 格式的图表。但注意热词搜索里有人问怎么生成结构图 skill我在实操中发现最大的坑不是画图本身而是图里文字的层级和配色规范。一个好用的结构图技能应该规定根节点怎么命名、分支层级上限是多少、什么情况用实线什么情况用虚线、配色板用什么。不然模型画出来的图结构对但丑得没法看。图片生成技能主要不是让 agent 直接作图而是让它管理图片生成的工程链路——比如根据需求选择模型、构造 prompt、指定比例、生成后做评估。这类技能更像是一个提示词工程工作流。社区里很多人分享的图片生成 skills 安装包其实本质就是一套写 prompt 的规范后处理脚本。新手建议先用现成的包后期再改造成适合自己的。LaTeX 排版技能热词里有怎么做一个 latex 排版 skills这个需求我在给学术论文做排版时也遇到过。一个合格的 LaTeX 技能应该包含章节结构模板、数学公式书写规范、浮动体figure/table管理策略、引用管理方式、以及中英文混排时的宏包选择。不然模型写出来的\documentclass可能没问题但一到复杂公式和长表格就崩。我见过模型生成的 LaTeX 在本地编译直接报错的情况挂了技能之后错误率能降到很低。3.3 我筛选社区 Skills 的三个硬性标准社区里 skills 数量越来越多但不是每个都值得装。我筛技能只看三条标准供你参考看维护者是否自己在用。如果一个 skill 的仓库里有 issue 讨论、有近期 commit、有使用示例说明维护者真的在跑它。反之那种半年没更新但 star 数虚高的大概率是只写不练。看技能描述是否收敛。好的 skill 描述会写明「这个技能不做什么」比如本技能仅用于数据可视化不做数据分析。描述写得越收敛触发越精准误伤率越低。那些描述里什么都想覆盖的技能实际用起来往往什么都做不好。看是否可审计。skill 本质是给 agent 的可执行指令里面有没有不明来源的脚本、有没有要求上传数据的操作必须拉开看一遍。我会在第五部分专门讲安全但这里先提醒一句不要闭眼装包。4. 从零开发一个自己的 Skills完整实操拆解4.1 决定一个 Skill 生死的描述字段怎么写到了这篇文章最实操的部分——自己开发技能。我以开发一个数据图表生成技能为例带你完整走一遍流程。首先要搞清楚一件事一个 skill 能被模型正确调用90% 取决于SKILL.md里的description字段。很多初学者把精力放在正文流程上结果描述写得稀烂模型根本不知道什么时候该用它。这个字段的作用就是让模型做该不该调用我的判断它写得越具体、越精确误触发率越低。我踩过最大的坑就是把 description 写得太宽。比如--- name: chart-helper description: 帮助用户生成各种图表。 ---这个描述等于没说。模型几乎无法判断各种图表的边界结果就是用户随便提一句给我看个走势模型都可能触发这个技能。更严重的是它跟其他技能会互相抢触发权。我打磨过之后改成这样--- name: chart-helper description: | 将结构化数据CSV/JSON/Pandas DataFrame转换为可视化图表时使用。 支持折线图、柱状图、饼图、散点图输出为 PNG 文件。 仅用于纯数据可视化任务不做数据分析、不做数据清洗。 如果用户要求的只是概念图、架构图或思维导图不要使用本技能。 ---对比一下这个描述里包含了触发条件有结构化数据要画图、能力边界支持哪些图、输出形式PNG、反向约束不做什么、什么情况不用。模型做匹配时就有了清晰的依据。我实测下来这样写之后触发准确率从 60% 提到了 90% 以上。4.2 编写 SKILL.md 正文让模型能照着执行的才是好流程写完整体的SKILL.md核心是正文部分。Claude Code 和 Codex 的 harness 都支持标准 Markdown模型会把它作为上下文的一部分来阅读、理解、执行。但这里有个关键点正文不是写给人类看的操作文档而是写给模型看的过程性指导。人看的文档可以直接运行以下代码但模型看的是什么时候发生什么判断、走哪个分支、注意什么边界。所以我的正文结构一般长这样# Chart Helper Skill ## 目标 将结构化数据转换为指定格式的可视化图表。 ## 前置条件 - 需要数据文件路径或 DataFrame 对象。 - 确认数据字段类型数值、时间、类别。 ## 执行步骤 1. 读取数据打印前 10 行 字段名确认数据完整性。 2. 如果数据包含缺失值提示用户是否填充或删除获得确认后再继续。 3. 根据用户指定的图表类型选择模板脚本。 4. 运行脚本生成 PNG 到 output/ 目录。 5. 用 PIL 检查 PNG 是否非空且尺寸合理如果失败重新生成。 ## 图表规范 - 字体使用 Noto Sans CJK避免中文乱码。 - 配色使用预设色板禁止使用默认颜色循环。 - 输出尺寸1600x900dpi 150。 ## 边界与禁忌 - 不执行数据清洗不输出交互式 HTML。 - 不要使用 seaborn 之外的库如 plotly。我刻意在正文里写了打印前 10 行确认数据再继续获得用户确认后再继续这种中间检查点。原因很简单模型在执行多步任务时很容易一条路走到黑中间步骤出了问题它会继续往下走最后输出一个错误结果。在流程里埋检查点让它在关键节点停下来确认能大幅提高成功率。这是我从无数次失败调试中总结出来的经验。4.3 本地调试的完整流程从技能被加载到输出可用写完SKILL.md和配套脚本后调试流程我建议按下面的顺序走第一步验证目录结构。确认SKILL.md在正确的路径下文件名一个字母都不能错。Skill.md和SKILL.md在 Linux 下是两个文件harness 只认SKILL.md。这一步最基础也是很多人翻车的第一站。第二步验证技能被加载。打开 Claude Code 或 Codex 会话直接问你现在有哪些可用技能看列表里有没有你的技能。如果没有说明路径或命名有问题。这个验证方式我在前面提过一次这里再强调每次改动目录后都要重新开一个会话再验证因为 harness 的扫描时机通常发生在会话创建时。第三步用最小测试样本跑一遍。找一个固定的小测试文件让 agent 执行这个技能观察它的行为。注意这里你要看的不是输出结果而是它的执行路径——有没有先读 SKILL.md有没有按步骤做检查有没有在中间节点停下来。如果它跳过了步骤直接出结果大概率是正文里的检查点写得不够强制。第四步多轮迭代 description。一个技能不是一次写完就结束的你需要反复调 description观察它在不同任务下会不会误触发。我通常会准备 5 个应该触发的用例和 5 个不该触发的用例然后逐一跑看命中率。直到该触发时触发、不该触发时坚决不触发这个技能才算能用。第五步用真实任务做回归。把技能放到你的真实项目里跑几天记录下每次失败案例回头调整正文和脚本。技能是活的它在使用中会不断暴露边界问题这是正常现象。5. 决定 Agent 上限的三个隐藏环节测评、记忆、安全5.1 怎么测评一个 Skills 到底好不好用从准确性到稳定性热词里有skills 怎么测评说明很多人在装了一堆技能之后开始意识到需要一套评估标准。我自己跑了一段时间之后总结出三个硬指标触发准确率给定一组该触发和不该触发的任务统计正确触发的比例。这反映 description 写得好不好。任务完成率在技能触发后任务能不能按预期完成。这反映 SKILL.md 正文的流程是否可执行、有没有漏步骤。输出稳定性同一个任务跑 5 次结果差异大不大。这反映技能是否约束了模型的随机性。输出稳定的技能才有工程价值因为可预期。我建议你可以建一个简单的验收表就是这种格式指标测试任务通过标准实测结果触发准确率「把这几个数画成折线图」100% 触发通过触发准确率「帮我写一首诗」0% 触发通过任务完成率读取 data.csv 生成 PNG输出文件存在且非空通过输出稳定性同一数据跑 5 次图表结构一致基本通过没有这套测评机制你装再多的技能都是盲人摸象你觉得它有时候好用有时候不好用但根本说不清楚问题出在描述还是正文还是脚本。5.2 Skills 与 Agent 记忆技能是更高维度的长期记忆在 agent 开发中记忆通常分成短期记忆当前上下文窗口和长期记忆向量数据库、存档等。但很多人忽略了第三种程序性记忆——也就是知道怎么做某件事的记忆。Skills 其实就是这种程序性记忆的载体。打个比方长期记忆是我知道北京烤鸭这道菜程序性记忆是我知道怎么从选鸭、切片、蒸饼到上桌的完整流程。你可以用 RAG 把前一种记忆灌进 agent但后一种记忆如果交给 RAG 去检索结果会很不稳定——因为向量检索返回的是碎片化知识不是严谨的执行步骤。这也是为什么我把 skills 和 agent 记忆分开讨论它们虽然相关但定位完全不同一个管事实一个管流程。实际项目中我见过有人把操作手册里的大段内容切块塞进向量库希望 agent 在需要时检索。结果就是检索到的内容总是差点意思。正确做法是把稳定的、不常变的执行流程写进 skill把动态的、跟具体用户相关的信息存进向量库。这样分工agent 既稳定又灵活。5.3 被忽视的安全边界Skill 是指令注入的重灾区最后说一个容易被忽视但极其重要的话题——安全。我在前面筛选标准里提过可审计这里展开讲。Skill 本质上是注入到模型上下文中的外部指令。这意味着如果一个恶意或来源不明的 skill 被加载它完全可以在 SKILL.md 里写一些引导模型执行危险操作的指令比如让模型把环境变量发到某个服务器、在本地执行任意 shell 命令、读取敏感文件并编码外传。这不是危言耸听社区里已经出现过这种案例。我自己的安全底线有三条只安装可审计来源的 skills。任何从非官方渠道拉下来的技能都要先打开SKILL.md和所有配套脚本通读一遍确认没有可疑的网络请求、没有未知的 base64 编码内容、没有让你输入密钥或 token 的操作。运行环境做隔离。给 agent 开发专门开一个容器或虚拟机跟重要的工作环境分开。像 pi agent 这类本地框架最好跑在受限权限的用户下不要给它 root 权限。禁止技能请求敏感凭据。正规技能不需要读取你的 API key、token 或密码。任何一个 skill 提出这种需求基本都是恶意或者极不专业的直接弃用。安全这块我宁可多说几句因为 agent 越强大被恶意利用的风险就越高。你给 agent 装上超能力的同时也要给它建牢笼。写在最后一个关于超能力的忠告我自己在实际使用中最大的体会是skills 不是装得越多越好。之前我试着把一个 agent 挂上十几个社区技能结果它的行为变得很不可控——因为技能之间会互相干扰模型反而不知道该听谁的。后来我删到只剩 3 个核心技能每个技能都反复打磨过 description 和执行流程整个 agent 的表现反而上了一个台阶。所以如果你刚开始接触我建议你别急着收集技能先挑一个你自己最常用、最痛的任务把它做成一个精雕细琢的 skill跑顺之后你自然就明白 skills 的整个运作逻辑了。最后再分享一个小技巧每次改完 SKILL.md 的 description记得重新起一个会话并在会话里用一句你会做什么来验证它是否理解了自己的边界这个习惯能帮你避开很多玄学问题。