如果你最近在折腾 AI Agent、写自动化脚本或者研究让模型更听话地执行复杂任务那“skills”这个词你一定绕不开。我身边好几个做智能体应用的朋友这两个月都在聊它。有人把 skill 比作“给 AI 配的一本说明书”有人叫它“外挂能力包”说得天花乱坠。其实没那么玄乎它就是一套让模型更稳定地完成特定任务的结构化方案。这篇文章我想把我自己从零开始折腾 skills 的经验完整拆给你看包括它解决什么问题、目录怎么设计、里面每一段内容该怎么写、实际能跑通的小例子还有我踩过的坑。无论你是刚接触 Agent 开发的新手还是已经在写复杂工作流的进阶玩家这篇应该都能给你一些可复用的参考。1. 重新理解 skills它不是插件而是“给模型的一份操作手册”1.1 为什么 Agent 会突然“失灵”问题到底出在哪先说个我自己的真实经历。之前我写过一个做竞品分析的 Agent让它在网上抓资料、读文档、最后生成报告。流程看着很顺结果一到真跑就翻车。模型不是不会用工具而是不知道“什么时候用”“用完怎么接”。它会抓取一堆无关紧要的页面也会在生成报告时把一个很基础的数据格式搞错。后来我把指令反复调整了很多次效果还是不稳定。问题其实不在模型本身而在“任务知识”没有和模型的工作机制对齐。模型本身有很强大的泛化能力但它不知道你的项目里那些具体的、约定俗成的操作细节。比如“什么是我们内部定义的有效线索”“报告里标题级别怎么定”“请求 API 时哪个字段该动态生成”。这些内容塞在系统提示词里会太长塞在代码里又写死最终你得到的就是一个“能力很强但老办错事”的 Agent。Skills 的出现就是来补这个洞的。它的核心思路是把某一项技能所需要的全部上下文单独拆出来放进一个目录让模型在需要的时候按需加载。这个加载不是像传统编程那样导入一个库而是把一份写好的“操作说明”注入到模型的上下文里。效果相当于你招了一个新员工不指望他什么都会但只要他遇到对应的工作就有一份 SOP 可以照着做。1.2 和插件、函数调用、提示词到底有什么区别很多教程喜欢把 skills 和插件plugins、函数调用function calling混着提但如果你真要开始落地一个项目这几个概念的差别得先弄清楚。我自己更愿意把它们放在一条链路里看待提示词是“告诉模型怎么做”函数调用是“给模型一个能执行的动作”而 skill 是“把怎么想、怎么做、用什么工具、按什么顺序、什么算对打包成一套完整流程”。打个比方函数调用相当于给模型提供了一把螺丝刀模型知道要旋螺丝的时候用它插件是给模型一套带把手的工具箱而 skills 则是“螺丝刀使用手册”它甚至能告诉模型“什么情况下选梅花头而不是一字头”“拧到什么力度算到位”“拧完要做什么检查”。这种差别很细微但实际用起来差距极大。我在实际项目里观察到一个很明显的现象如果只靠函数调用模型能正确调用工具但经常忽略调用后的校验逻辑如果只靠提示词指令一长模型就“注意力稀释”而配置了 skill 之后模型会在合适的时间点主动把 skill 内容读进上下文按里面的步骤执行。这背后其实是利用了 agentic 工作流里的一个特性——模型不是一次性看完所有内容而是分阶段决策需要时就“翻手册”。2. 动手前的关键设计一个 skill 的核心结构应该怎么定2.1 先想清楚你真正要封装的是“知识”还是“流程”我自己第一次封装 skill 时犯过一个错误把实现细节塞得太多以为越详细越好。结果模型每次执行都变得非常僵硬换个输入条件它就不知道怎么处理。后来我慢慢明白skill 封装的不是死流程而是“完成该任务所需的决策边界”。比如说我封装过一个写周报的 skill。如果我只写“把工作内容填进模板”这就是死流程。但如果我写清楚“周报的第一段必须写业务结论、第二段写关键数据、第三段写问题与计划数据口径与上周报表保持一致”那模型就知道在不同输入下该往哪个方向调整。知识和流程都要有但知识——也就是判断依据——才是灵魂。所以你在设计 skill 目录之前先问自己一句这个任务里模型最容易在哪个环节犯错把这个环节的决策依据写清楚比罗列一万个步骤更有用。2.2 目录结构与命名规范决定了 Agent 的加载效率一个 skill 在代码层面其实就是一个文件夹里面放一个说明文档外加若干参考资源。Anthropic 在 Agent Skills 里推荐的目录结构大概是这样的我也沿用了这套来做skills/ └── competitor-analysis/ ├── SKILL.md ├── reference/ │ ├── report-template.md │ └──>--- name: competitor-analysis description: 用于系统性地分析竞争对手的公开产品信息、定价策略与用户口碑。仅当用户要求了解某公司或产品的竞争格局时使用不用于泛泛的行业研究报告。 ---这段描述里我把“什么该用”写清楚了也把“什么不该用”点出来了。别小看后面这一句边界约束越清晰模型误调用的概率越低。我自己就遇到过写了个“资料收集”类 skill因为描述没写边界模型在用户聊家常时都试图加载它正确率反而下降了。3. 核心实操从零到一写一个真正能跑的 skill3.1 先用一个最简单的“报告优化器”练手我第一次完整跑通一个 skill项目目标是“帮助非专业用户优化周报的表达”。这个需求足够简单但又有明确的决策点非常适合拿来做实验。整个 skill 的 SKILL.md 核心内容我写得很克制没有一上来就铺满模板。下面这个是简化后的实际结构--- name: report-polisher description: 将用户输入的周报草稿改写成结构清晰、表达专业的版本。保留原有事实与数据只优化逻辑、句式与用词。当用户给出周报、月报类文字草稿时使用。 --- # Report Polisher ## 你的任务 将用户输入的工作周报草稿改写为高完成度版本。你只做表达优化不做事实补充。 ## 关键处理原则 - 保留原文中的所有业务事实、时间节点、数据指标禁止自行“脑补”。 - 每个工作块建议按“背景-动作-结果”三层组织。 - 第一句话必须是该工作块的核心结论避免“本周我继续跟进”这类无效开头。 - 数据相关句子前置说明性句子后置。 ## 处理步骤 1. 提取原文中的事实要点与各项数据。 2. 将内容按优先级排序业务结果靠前过程细节靠后。 3. 重写每个工作块的描述确保结论先行的表达方式。 4. 通读一遍保证没有遗漏重要信息没有改变原始含义。 ## 输出格式 以 Markdown 输出使用二级标题分隔不同工作块。这个 skill 里没有写死任何模板没有指定固定的语气词但它把最关键的决策依据写清楚了保留事实、结论先行、数据前置。就凭这几条模型输出质量已经比直接丢给模型“帮我润色一下”稳定很多。很多人会把这种任务直接写进系统提示词我当时也这么想过。但你会发现一个问题系统提示词里如果同时有任务 A、B、C 的完整 SOP模型在处理任务 A 时依然会受到 B 和 C 内容的影响。而用 skill 的方式模型只在需要时读取对应说明上下文更干净执行准确性更高。3.2 加一点“负面约束”输出效果立刻质变我第一次写的 report-polisher 版本其实效果一般问题出在模型输出的风格“太 AI”了一看就是机器改写。后来我在 skill 里加了一段负面约束效果一下子就不一样了。## 禁止事项 - 禁止使用“成功完成”“圆满达成”“进一步推进”之类空洞表述。 - 禁止在改写后添加任何原文没有的结论性修饰语。 - 禁止将原文里的口语化表达全部替换为正式表达保留适度个人语气。 - 如果原文本身足够清晰仅做小幅调整不要为改而改。就这一段输出的自然度立刻上来了。我发现很多 skill 在写规则时只写“要做什么”很少写“不能做什么”。但模型恰恰需要明确的行为禁区来抑制默认倾向。这个经验几乎可以套到任何类型的 skill 里。3.3 引入脚本和参考资源让 skill 能做更多事光有 SKILL.md很多任务其实做不完整。比如我有一次要做竞品价格监测光靠模型去推理价格变化是不够的得让它自己去请求 API 拿实时数据。这时候 skill 目录里的 scripts 就派上用场了。我在 scripts 里放了一个简单的 Python 脚本 fetch_competitor.py作用是根据给定竞品名称返回产品名称、价格区间和最近动态。SKILL.md 里会有这样一段## 使用脚本 1. 当用户提供竞品名称时运行 python3 scripts/fetch_competitor.py --name 竞品名称。 2. 将脚本输出的 JSON 数据作为后续分析的基础不要擅自改动其中的字段值。 3. 如果脚本执行失败根据错误信息判断是网络问题还是参数问题并向用户说明。这里有个容易踩的坑模型不一定能在对话环境里直接执行 Python 脚本你需要通过 framework 或自己的 executor 把“运行脚本”的能力暴露给模型。换句话说skill 本身只是定义了“可以运行这个脚本”但如果 Agent 没有连接一个能执行代码的工具模型还是会卡住。所以设计 skill 时要先确认自己项目里有没有对应的工具底座。参考资源reference的使用思路类似。不要把大段模板直接写进 SKILL.md测试下来模型在前置信息过多时反而忽略真正要用的细节。正确做法是把完整模板放进 reference 目录在 SKILL.md 里指向它并告诉模型“输出格式参照 reference/report-template.md”。这样模型在需要时主动打开阅读平时不影响主流程。4. 编排多个 skill真正的 Agent 工作流是“多本手册”协同4.1 让不同 skill 各管一段Agent 工作流就活了单个 skill 再强也只是单个任务环节。实际做 Agent 项目时最有趣的是把多个 skill 编排在一起让模型像员工一样在不同阶段调用不同的“工作手册”。我自己搭过一个内容生产 Agent里面就同时挂了三个 skill资讯收集、行业分析、写作出稿。每个阶段模型会自动选择对应 skill 去加载。这个编排过程不需要多复杂的调度框架关键靠两个东西一是每个 skill 的 description 写得足够精准让模型能区分“现在该用哪个”二是在更高层的系统提示词里定义工作流的主逻辑。比如我写系统提示词时会说“先使用资讯收集 skill 获取素材再用行业分析 skill 归纳要点最后用写作出稿 skill 生成文章。”模型会照着这个主逻辑走然后在对应节点加载具体 skill。有一次我测试故意删掉了资讯收集 skill 的 description 里的边界描述结果模型在行业分析阶段也尝试加载它输出质量明显变差。后来我把 description 改了明确声明“本 skill 仅用于素材阶段的原始信息获取不要用于归纳分析”报错率立刻降下来了。4.2 权限与灵活性的平衡是编排时最容易翻车的地方很多人在编排时喜欢把步骤写得非常死要求模型必须按顺序执行。但实际跑几轮你就会发现用户的输入是充满不确定性的模型需要一定的灵活性才能处理好边界情况。我自己取舍下来的做法是在 SKILL.md 里把“标准流程”和“分支情况”分开写。比如资讯收集 skill 里如果用户没有明确指定来源模型可以从推荐清单里选如果用户给了特定来源就按用户要求来。这种“默认路径 弹性分支”的结构让 skill 在真实场景下不至于僵化。同时在编排时注意控制每个 skill 的作用范围不要试图让一个 skill 把所有事都做完。Agent 工作的单位是“决策”每个决策点的上下文越清爽模型判断越准。宁可多配置几个 skill也别把一个大 skill 写成巨型文档。5. 避坑实录我在 skills 落地中踩过的 5 个典型问题5.1 skill 描述太宽泛模型频繁误加载这是我遇到的第一个问题。我给“通用资料收集”这个 skill 写描述时只写了“收集用户需要的信息”结果模型在所有需要一点背景知识的地方都调用它。上下文被塞进很多无关内容执行质量直线下降。解决方法很简单把 description 写“窄”一点。明确说出“仅在用户要求收集外部资料时使用不用于基于已有知识作答”。边界清晰之后误调用的情况基本消失。5.2 SKILL.md 写得像论文模型反而不看了另一个常见问题是内容过多。很多教程会让你尽量写详细但实际操作下来SKILL.md 超过 150 行之后模型对里面指令的执行一致性反而下降。核心规则要在前面突出细节性内容放进 reference 或者用“如果遇到 X 情况参考 reference/Y”这样的指引。我自己习惯把每个核心原则控制在 5 行以内步骤控制在 8 步以内超过的部分全部挪进参考文档。这样模型读起来负担小执行聚焦度明显更高。5.3 忽略了与底层工具的连接skill 成了空壳skill 不是高配版提示词它最后的落地依赖于底层工具能力。比如你要让模型读数据库里的表skill 里写“读取数据表”没有用你必须给模型暴露一个 read_database 这样的函数调用能力。skill 只是告诉模型“什么时候该用到这个能力、用的时候注意什么”真正干活的还是那套底座。我刚开始做的时候就把注意力全放在 skill 的文本上结果模型总在正确的时间点提出“我需要读取数据”但根本没有对应的工具可以执行。后来我先梳理项目里已有的工具集再去设计 skill 的操作流程顺畅多了。5.4 没有做版本管理改一次就“翻车”skills 本质上是代码目录但它又不像代码那样有直觉上的“报错”机制。改一个描述可能模型行为就完全变了。我早期经常“盲改”改完没有对比测试上线后才发现行为异常。现在我的习惯是每个 skill 建立独立版本标签修改后先在小范围测试集跑一遍确认输出质量符合预期再放进主流程。这里分享一个很笨但有效的方法准备 5 条代表性的测试输入每次改动之后先跑这 5 条看结果差异再决定是否合并。这个方法帮我拦下了至少三次回归事故。5.5 容易忽略多模型兼容性最后一条经验如果你的 Agent 后期可能切换底层模型skill 的表现可能完全不同。同一个 SKILL.md在顶级模型上执行得很顺换个小参数模型可能就“理解不了”。后来我会在 skill 里把关键决策点写得更加直白减少需要“领悟”的内容。这样做的附加效果是即使在大模型上执行输出稳定性也更高。6. skill 还能怎么扩展从单点功能到系统性工作流6.1 多 skill 之间的信息交接值得在一开始想清楚我的经验是如果只是为了一个简单任务大可不必上 skills。但一旦你的 Agent 需要完成一个多步骤的复杂工作skill 的模块化价值立马体现出来。比如说我做的“竞品研究 Agent”主流程是用户给出一个竞品名字Agent 先调用 fetcher 脚本拿原始数据再基于数据做结构化分析最后生成一份包含价格对比、功能差异、优劣势判断的报告。这三个步骤对应三个 skill数据获取、分析框架、报告输出。其中最有意思的不是单个 skill 怎么写而是三个 skill 之间如何“交接”。我的做法是数据获取 skill 的输出统一 JSON 结构分析 skill 依赖这个 JSON报告 skill 只接收分析结论。这种接口式的设计让每个 skill 可以独立迭代不会牵一发动全身。做 Agent 项目时先把 skill 之间的输入输出协议定好比写任何具体逻辑都重要。6.2 写 SKILL.md 的经验已经可以反哺团队规范到了后期我发现自己写 skill 的收益不只在具体执行效果上更重要的是它倒逼我梳理了团队的“隐性知识”。以前很多操作经验只存在老员工脑袋里现在可以沉淀成“模型也能读懂”的文档。这对个人的项目复盘、对团队的知识管理都有很直接的价值。所以我现在的建议是哪怕你只是做个人项目也值得从一个小 skill 开始练手。挑一个你重复做过多次、有明显固定套路、但又有不少隐性判断的任务把它封装成 skill。你会在封装过程中更加理解 Agent 的决策逻辑也会更明白模型在复杂任务中的优势与局限。一个小技巧是当你觉得某个任务自己已经“闭着眼睛都能做”的时候就是封装成 skill 的最好时机。这份熟练本身就是最好的知识素材来源。