AI Agent Skills实战：从SKILL.md到可复用技能库设计

“skills”这个标题给得特别简洁但做过 Agent 应用的朋友应该都有同感现在这波 AI 编程和智能体开发里skills 已经从一个可选项变成了刚需。我最早接触这个概念是在折腾 Claude 的 Agent 功能时后来发现不管是写自动化脚本、处理文档、还是给大模型配工具把能力拆成一个个独立、可复用的 skill整个项目的稳定性和可维护性完全不一样。这篇文章我想把这块的经验完整拆开聊一聊覆盖技能的设计思路、文件组织、参数配置和避坑细节适合正在做 Agent、AI 工作流或者准备接大模型 API 的朋友参考看完你基本能自己搭一套可复用的技能库。1. 为什么我最终把所有 Agent 任务都拆成了 Skills1.1 摆在眼前的现实问题先说说我最早碰到的困境。一开始做 AI 自动化我习惯把所有指令都塞进 system prompt 里写一个超级长的“总纲”里面混着角色设定、业务规则、输出格式、工具说明甚至还有几个 few-shot 示例。结果跑起来之后问题非常明显模型经常顾此失彼前面提到的要求到后面就忘得一干二净修改一个细节要扫描整个 prompt 找位置想复用某段能力只能复制粘贴改一处漏一处。后来我尝试把功能拆成独立的函数、独立的脚本去调用确实解决了一部分混乱问题但新的麻烦也来了——Agent 不知道什么时候该用哪个工具也不会根据当前上下文调整参数。代码是拆了模型和工具之间却缺少一层“智能粘合层”。1.2 Skills 到底解决了我什么痛点Skills 本质上就是这层粘合层。它把一段任务描述、一组可选参数、相关的脚本/参考文档以及输出模板打包成一个单元Agent 看到 SKILL.md 之后能自己判断要不要调用、怎么调、传什么参数。这比我写死逻辑要灵活得多。我实际跑下来的感受是拆成 skills 之后有三个非常明显的好处上下文按需加载每次只把当前 skill 相关的文档和脚本喂给模型不用从 5000 字的总纲里翻找。Token 占用降了模型反而记得更牢。能力可插拔新项目要复用某个技能直接把目录拷过去或者用路径引用一下就完事了。不需要再改大段 prompt。迭代成本低某个 skill 表现不好单独调它的描述、脚本、示例就行不影响其他任务。这就是模块化的红利。所以我的建议很直接如果你准备长期做 Agent 相关项目skills 这种组织方式是值得认真投入时间去掌握的。它不是花架子而是真正能在工程化落地上带来收益的设计。2. Skill 的文件结构一次讲透2.1 最基础的目录长什么样先给你看一个我常用的 skill 目录结构以“周报生成器”为例skills/ └── weekly-report/ ├── SKILL.md ├── scripts/ │ ├── collect_stats.py │ └── format_markdown.py └── references/ ├── report_template.md └── examples/ └── good_report.md这里面最重要的只有两个文件SKILL.md和可选的scripts/。前者是一份 Markdown 格式的说明文档告诉模型这个技能是干什么的、需要什么输入、输出是什么样的后者是真正会被执行的代码。我见过有人把SKILL.md写成了“读后感”四五百字全是套话模型看完并不知道自己该干嘛。这里我强调一下SKILL.md 是给模型看的「操作手册」不是给人类看的需求文档所以描述必须聚焦在“做什么、怎么做、输出长什么样”上。2.2 SKILL.md 里的元信息别乱写先看一个标准的元信息示例--- name: weekly-report description: 根据用户提供的原始工作记录生成结构化周报。仅在用户要求生成周报或总结一周工作时使用。 ---这两行的作用非常关键。name是技能的唯一标识模型在决策时会引用它description则是触发条件决定了什么时候这个 skill 会被想起来。我的个人习惯是description里必须包含场景、任务、前置条件和触发指令在测试中我发现只要 description 写得太宽泛比如“处理报告”模型就会在用户只是想修改某个句子时也误触发技能。反过来写得太窄比如“只在用户输入生成周报四个字时使用”那用户说“帮我总结一下这周干了啥”技能就不会被激活。找到一个合理的语义边界是 SKILL.md 元信息设计里最需要花心思的地方。2.3 参考内容与脚本怎么放最合理很多人会问“脚本和文档到底应该放在 SKILL.md 里面还是放外部文件引用”我的经验是能放外部文件就放外部文件。原因有两个一是 SKILL.md 的篇幅越短模型的加载和阅读效率越高二是脚本和文档往往是可复用的拆出来更方便单独测试和维护。references/目录用来放模板和示例。注意这里的示例要选“高质量的正例”我会特别标注“这是好例子请模仿其结构”模型会从这些示例里学到具体的格式偏好而不是靠抽象描述猜测。scripts/目录则放真正会被执行的代码。脚本的作用通常是做一些模型不擅长的事情比如算数、读数据库、批量改格式。能交给 Python/Node 做的就不要让模型“硬想”这样可以显著提升准确性。3. 手把手写一个自己的 Skill3.1 先定边界这个 Skill 管什么、不管什么在写任何代码之前我会先在白板上写下三句话这个技能的输入、输出、边界。以周报生成为例输入用户提供的一周工作纪要可能是零散的流水账。输出一份 Markdown 格式的周报分成“本周完成”、“下周计划”、“风险与问题”三部分。边界不负责统计数据交给脚本不负责发送邮件那是另一个技能的事。把这个边界写清楚后面写 SKILL.md 的描述才不会跑偏。边界越清晰模型在决策时就越不容易犹豫也不会擅自扩展功能范围。我的另一个建议是先做一个能跑通的最小版本再加功能。第一次写 skills 的人通常会犯贪多嚼不烂的毛病一开始就在脚本里加了 Excel 读取和钉钉通知结果连最基本的格式都保不住。我通常第一版只做“用户粘贴文本模型返回排好版的 Markdown”验证没问题后再加脚本逐步完善。3.2 用代码规范约束输出光让模型“写得好看”不够我会在 SKILL.md 里加一个强制约定要求模型必须调用脚本中的函数来格式化输出。这是提高输出稳定性的一个技巧把容易被模型自由发挥的部分替换成固定代码逻辑。# scripts/format_markdown.py def render_weekly_report(items, next_plan, risks): lines [] lines.append(# 周报\n) lines.append(## 本周完成) for item in items: lines.append(f- {item}) lines.append(\n## 下周计划) for plan in next_plan: lines.append(f- {plan}) lines.append(\n## 风险与问题) for risk in risks: lines.append(f- {risk}) return \n.join(lines)脚本本身不负责“理解语义”只负责“按固定格式渲染”。模型要做的只是提取信息然后调用函数。这一步把输出格式的方差压到了最低实测下来效果比直接让模型写 Markdown 稳得多。别小看这种“人机协作”的分工方式它其实遵循了一个原则凡是确定性强的操作尽量用代码执行凡是开放性强的操作留给模型生成。格式、计算、数据清洗这类任务完全不适合模型自由发挥。3.3 测试 Skill 的正确姿势写完不是直接上线我会准备一个测试用例集包含正常情况、边缘情况和异常情况。然后一行行模拟用户输入去试。一个典型的边缘情况是“用户提供的内容不足”。比如用户只写了一句话“这周主要做了后台重构”没有更多细节。这种时候 skill 应该输出一份结构完整的周报但里面内容写到最简而不是捏造细节。我会在 SKILL.md 里明确写如果用户提供的信息不足以填写完整周报请在对应部分保留标题并注明“信息不足请补充”不要编造工作内容。这种“强制诚实”的约束在 AI 自动化里非常重要。模型太喜欢“补全”了你不约束它它就会给你编出一份一模一样的周报。4. 我踩过的坑以及怎么绕开4.1 提示词太长Agent 直接“失忆”我第一次写 SKILL.md 时一口气写了 800 多字从背景介绍、知识讲解、历史沿革写到注意事项洋洋洒洒。结果实际调用时模型明显“抓不住重点”输出格式经常不对该调脚本的时候不调不相关的内容倒是写了一大堆。后来我做了个对比实验把 SKILL.md 精简到 250 字左右只保留任务目标、操作步骤、输出规范和一句触发条件准确率立刻上了一个台阶。原因其实很好理解模型也是靠有限的注意力窗口做决策的描述越啰嗦核心指令占用注意力的比例就越低。建议SKILL.md 超过 500 字就要警惕优先压缩掉背景描述和“鼓励性”的废话比如“请确保报告美观易读”——这种话模型听了等于没听。4.2 脚本写太“聪明”反而害了 Agent有一次我给某个技能写脚本时为了让它“更智能”在 Python 里加了一堆判断逻辑自动识别输入格式、自动转化时区、自动推断星期。结果调用时脚本频繁报错模型还得花额外 token 去处理报错信息。这让我意识到一个核心原则脚本要简单到“一眼能看懂”而不是“看起来很牛”。脚本在 Agent 架构里扮演的角色是“精准的简单工具”不是“万能智能体”。凡是需要复杂语义判断的逻辑一律留给模型脚本只做那些输入输出可预期的操作。遇到解析不了的输入直接返回错误信息反而是更高效的交互方式。4.3 权限给太大差点删了配置还有一个非常值得说的经验教训。刚开始我在 skill 的脚本里加了一个“清理临时文件”的功能为了让 Agent 更自主脚本里用了一个比较宽泛的目录匹配规则。结果在一次测试中脚本把另一个项目目录下的配置文件当成了临时文件给清理掉了。从那以后我给自己立了规矩脚本默认以只读模式运行除非明确需要不提供删除/覆盖能力。文件操作必须基于用户显式确认的文件路径不能用“猜”的匹配规则。所有写操作先写入临时文件确认无误后再覆盖原文件。这不算什么高深技术但自动化任务一旦跑起来破坏性操作的后果往往比你想的严重。宁可让 Agent 多问一句也别让它多删一个文件。4.4 Skill 之间的调用关系单个 skill 写多了以后我遇到的新问题是怎么让它们协作。比如周报技能需要从“项目管理”技能里提取任务数据一开始我把这些逻辑全写在一个技能里结果技能之间耦合越来越严重改一个就得改另一个。后来我转向“一个技能只做一件事但可以通过约定读取共享的中间结果”的设计方式。数据可以先用“数据导出”技能生成统一的 JSON 或 Markdown 文件另一个技能再去读取。不需要互相调用协作通过数据层完成。这个设计简单有效也符合低耦合高内聚的原则。5. 几个让 Skills 更好用的额外经验5.1 善用“最小示例”而不是“完整模板”在 references 目录里我通常不放那种几十行的完整长文档因为模型对照着长模板写很容易陷入“只改几个词其他生搬硬套”的模式。我更倾向于放一份“最小示例”里面只保留核心结构和两句示范台词再配一个简短的“坏例子”说明为什么不够好。给模型提供对比性反馈往往比堆叠大量正例更有效。5.2 参数命名影响模型的判断有次我调试一个技能发现模型总是把“日期范围”和“截止日期”两个参数搞混。我一看 SKILL.md里面的参数名写得非常随性一个叫 date一个叫 deadline语义区分度太低。改成 start_date 和 due_date 之后问题立刻消失了。这个细节说明给模型看的参数名本质上也是指令的一部分。参数名要尽量符合模型训练语料中的常见语义别用缩写也别模糊命名。5.3 定期回看和清理技能库技能越攒越多之后我发现有些技能几个月用不上有些功能互相重叠。这时候我会定期做一次“技能体检”把不再使用的技能归档把重叠的技能合并。一个干净、精简的技能库能让 Agent 的整体判断质量明显提升。因为技能太多模型光是从一堆候选里选一个合适的都会出现犹豫和误选。我习惯用一个简单的表格记录每个技能的调用次数和最近调用时间超过两个月没调用的先归档。别怕删好的技能留着偶尔翻出来看看还能得到不少优化灵感。最后再分享一个小技巧也是我最近才养成的习惯每次给技能加新功能时我会同步更新它的description。很多人只改脚本、不改描述结果模型根本不知道这个技能的技能范围已经变了。把“技能版本号”和“变更日志”写进 references 里长期维护会轻松很多。技能不是写完就能一劳永逸它是需要持续维护的活体资产而你把功夫花在组织方式上它回报你的将是稳定、可复用的生产力。