最近几个月，“skills”这个词在我身边的出现频率突然高了起来。如果你也在折腾AI Agent相关的项目，大概率已经碰过它——不是指“人要学会多少种技能”，而是一种把Agent能力封装成标准化模块的做法。简单说，skills就是给大模型写一份“操作手册”，让它接到一个具体任务时，知道该用什么工具、按什么顺序执行、中间有哪些坑要绕开，以及结果要整理成什么样子。
我最初接触这个概念时也犯过迷糊：不就是一个带说明文档的脚本吗？这和直接写一大段prompt有什么区别？直到我自己在项目里踩了几次坑、把Agent从“能跑”调到“真能复用”之后，才意识到skills这套机制解决的根本不是“会不会写代码”的问题，而是“大模型怎么稳定复现复杂操作”的问题。这篇文章就围绕skills展开，讲清楚它是什么、为什么需要、怎么写出一份能真正被Agent调用的skill，以及我在实操里遇到的那些典型问题和排查思路。适合正在做Agent开发、想让自己的应用具备可复用能力的开发者，也适合刚接触这个大方向、想找个切入点入手的读者。
1. 先把Skills这东西掰开揉碎讲清楚
1.1 一次“翻车”让我彻底理解了Skills的定位
我在两个月前接手过一个内部数据分析Agent的优化任务。这Agent本身已经能对话，用户问一句“本季度各渠道的转化率怎么样”，它也能在知识库里检索文档、拼出回答，但有个毛病特别要命：凡是涉及多步操作的任务，它就很容易“发挥不稳定”。
举个例子，用户要求“把上个月的订单数据按省份汇总，再和去年同期对比，最后生成一张表格”。这Agent的表现是：有时候能调用Python正确读CSV；有时候读完了文件，结果在“对比去年同期”这一步就开始胡编，自己生成了一个根本不存在的去年同期数；还有时候它倒是想调用脚本，但不知道应该把哪些参数传进去，于是就去猜，一猜就错。整个流程起码要看它试错三四次，偶尔还得我在中间手动干预。
后来我把这个任务拆成了多个步骤，写进了一个skill文件里，让Agent在识别到“按月汇总订单”“做同比对比”这类需求时，先去读那份SKILL.md，按里面规定的顺序执行，每一步用什么参数、结果落到哪里都写清楚。效果立竿见影：同一类任务的完成率从“碰运气”变成了“基本稳定”。也是从那次之后，我才真正想通了一件事——skills本质上不是“指导大模型做事的咒语”，而是把一次复杂操作的过程标准化、文档化，让模型有据可依。
1.2 Skills和普通Prompt、传统工作流的本质区别
刚开始很多人会问：我直接在系统提示词里写清楚步骤不行吗？为什么要单独搞一个skills文件？这个问题我自己也纠结过。如果你只是把步骤写在system prompt里，确实能管住一部分行为，但随之而来的三个问题很难绕开。
第一是上下文长度。一个复杂任务的完整操作手册可能有两三千字，如果你同时要给Agent配置十几个不同领域的能力，全部塞进system prompt，token开销会非常吓人，而且模型在长文本里面对“眼下这个任务到底该用哪一段规则”的判断也会变模糊。skills机制则不同——模型先看到的是每个skill的简短描述，只有当它判断当前任务符合某个skill的触发条件时，才会去加载那份完整的文档。相当于你给了它一个图书目录，它需要哪本再抽哪本，而不是把整座图书馆的内容都提前背下来。
第二是复用性。写在system prompt里的步骤，是和你当前的Agent耦合在一起的。你换个项目、换个应用场景，那些规则就得重新复制粘贴。而skill是一个独立文件，理论上可以放到任何Agent工具链里，只要框架支持读取SKILL.md这样的结构，它就能被识别和调用。我后来把同一个数据处理skill从内部工具的Agent里，直接搬到另一个面向外部客户的项目中，中间几乎没改代码，只是微调了描述文字。
第三是维护成本。传统工作流（比如硬编码的if-else流程）一旦步骤有变化，要改代码、要重新部署。skill则把“做什么”和“怎么做”以文档形式外置，改步骤只需要改Markdown文件里的一段文字，回调、重启都不用动。这也是为什么很多Agent框架（像Claude的Agent Skills、Semantic Kernel的Skills体系）都选择了“文档驱动”而不是“代码驱动”的路线。
1.3 我对一个好Skills的判断标准
在动手写之前，先明确什么样的skill才算合格。我自己现在会用几个指标来评估：
- 触发边界清晰：描述里能说清楚“什么场景下该用它、什么场景下不该用它”，尽量避免和其他skill的描述重叠。
- 步骤可执行：正文部分要拆到“模型不需要猜”的程度。比如“将下载的CSV文件放到data/目录下，命名为latest_report.csv”，这种指令比“把数据准备好”靠谱一百倍。
- 输入输出有约定：定义好需要哪些参数、以什么格式传入、产出物放在哪里。没有这层约定，模型每次发挥都可能不一样。
- 有失败保护：写明遇到明显异常时应该怎么办——是停止并告知用户，还是尝试一次替代方案。默认情况下，让模型自动决策“再试一次”不可靠，容易导致一连串副作用。
2. SKILL.md的灵魂：结构设计与描述策略
2.1 一份标准SKILL.md长什么样
目前最常见的skill描述格式是Markdown文件，核心文件名是SKILL.md。我用过几个不同框架的skill，结构大同小异，完整范例如下：
--- name: monthly_report_generator description: 生成月度经营数据分析报告。当用户需要整理月度销售/运营数据、同比环比分析、或要求输出周报/月报时使用。 version: 1.2.0 --- # 月度报告生成Skill ## 何时使用 - 用户提供或指定了包含销售/运营数据的文件，并要求汇总、分析、生成报告 - 用户提到“月报”、“周报”、“同比”、“环比”、“数据复盘”等关键词 - 不适用场景：用户只要求普通聊天对话，不涉及具体数据分析时，不要调用本skill ## 输入参数 | 参数名 | 类型 | 必填 | 说明 | |------|------|------|------| | data_file | string | 是 | 原始数据文件路径，支持csv/xlsx | | report_period | string | 是 | 报告周期，格式YYYY-MM | | dimensions | string[] | 否 | 需要分析的分组维度，默认按省份 | ## 执行步骤 1. 加载数据文件，校验文件是否存在、字段是否完整。 2. 按report_period过滤数据，排除不在该月份内的记录。 3. 按dimensions分组汇总关键指标（营收、订单数、转化率）。 4. 如果有历史数据文件，计算同比和环比；没有历史数据则只输出当期绝对值。 5. 将结果写入output/report.md，包含汇总表格和关键结论。 ## 注意事项 - 原始数据中日期字段统一为YYYY-MM-DD格式，遇到其他格式先尝试转换。 - 对缺失值不自行填充，只做统计排除；若缺失比例超过30%，需在报告中显式说明。 - 不要修改原始数据文件，所有处理结果写入output目录。这份文档里，最重要的两处是frontmatter里的description和执行步骤。前者决定模型“什么时候想到它”，后者决定模型“具体怎么跑”。两者缺一个，skill的实际效果都会大打折扣。
2.2 description写不好，模型根本不知道有你这个Skill
我见过很多新手写的skill，第一版description大概长这样：“用来处理数据的。”问题是，Agent在运行时会收到几十个不同skill的描述，它需要靠快速判断来决定调用哪个。描述太笼统，它可能在你期望它用数据skill的时候，选了另一个看着更“像那么回事”的skill；或者更糟，它觉得哪个都不合适，干脆自己瞎编步骤处理。
一个好的description应该做到两点：触发条件明确、反例清晰。比如上面那个例子里的描述，前半句“当用户需要整理月度销售/运营数据、同比环比分析、或要求输出周报/月报时使用”是正向触发条件，后半句“不适用场景”则给了模型一个排除依据。实际测试中，加了这半句之后，误调用率下降得非常明显，模型不会在用户聊到“报告领导工作进度”这种话题时，也把数据skill拖出来跑一遍。
另外，description里不要塞太多形容词和情感色彩。“快速生成漂亮的可视化报告”这种话模型无法稳定理解。你要用动作和条件来描述，而不是用效果词。
2.3 正文的“可执行性”决定了下限
正文部分解决的是“模型怎么做”的问题。很多人的skill正文其实是一大段论述性文字，比如“先读取数据，然后对数据进行清洗，接着分析同比，最后输出报告”。这套话模型能看懂吗？能。但它可执行吗？不够好。因为它没有给出具体的判断规则和操作边界。
比如说“数据清洗”——到底清洗什么？日期格式不对算不算？缺失值要怎么处理？重复行要不要删？你如果不写清楚，模型就会按照自己训练时的习惯来“自由发挥”。不同模型、不同版本的自由发挥结果还不一样，这就是很多Agent项目“结果时好时坏”的根源。
我的经验是，正文里尽量把条件判断写成明确的映射规则：“如果A，就执行B；如果遇到C，则输出D并停止。”把“模糊地带”压缩到最小。比如上面例子中的“缺失比例超过30%时要在报告中说明”就是一条边界规则。它不需要模型去发挥创造力，只需要它照做。
3. 实操：从零构建一个可以稳定复用的Skill
3.1 选对场景是第一步：把重复性最高的事情拆出来
动手写skill前，先别急着想“我要做一个多牛的功能”，而是先盘点自己日常工作中哪些事情是重复的、多步骤的、且带一定判断逻辑的。这类事情是最适合封装成skill的。
我自己的经验是以“月度运营数据复盘”为例，这个场景几乎每个做运营或数据的人都会遇到：拿到一个数据文件，按地区、按渠道统计各项指标，算一下环比和同比，再生成一份Markdown格式的总结。这个过程步骤很多，但逻辑高度固定，而且每月的处理流程几乎一模一样。以前每次都要跟Agent交代半天背景，现在一个skill就能搞定。
选场景时要注意，不要选太宽泛的，比如“写文章”“做计划”这类的，边界太模糊，你很难在文档里定义清楚触发条件和执行步骤。也不要选太细碎到只有一步操作的，比如“把CSV转成JSON”这种一个命令就能完成的事情，直接用脚本就行，没必要封装成skill。合适的是那种“要跑3到10个步骤、每一步有判断分支”的任务。
3.2 从初版到稳定版：我给SKILL.md做了三次迭代
第一版的时候，我犯了个经典错误：把执行步骤写得太粗。当时的步骤里有一条“计算同比”，结果测试Agent跑出来之后，它居然把计算逻辑写成“本月数减上月数”。同比应该是“（本月数 - 去年同期数） / 去年同期数”，它之所以算错，是因为文档里没写公式。模型在遇到开放表述时会自己补一个“最常见”的解释，但这个解释不一定是你想要的。
所以我立刻迭代了第二版，把关键指标的全部计算公式都写成显式文本，例如：
- 环比增长率 = （本期值 - 上期值） / 上期值 * 100% - 同比增长率 = （本期值 - 去年同期值） / 去年同期值 * 100% - 当上期值或去年同期值为0或负数时，跳过计算，在报告中标注“无法计算”第三版迭代是因为我在测试中发现，Agent在生成报告时，喜欢把原始数据的单位偷偷改掉。明明数据文件里写的是“元”，报告里却变成了“万元”，我核对时差点被误导。原因就是原始SKILL.md里没有约定单位。后来我补上了一条：“所有数值在报告中保持原始单位，不换算、不缩写；如果百万级数据导致阅读不便，可以增加一列为缩放后的数值，但必须保留原始值。”
这三版迭代让我意识到一个道理：skill文件不是写给“理想模型”看的，而是写给“当前实际会越界的模型”看的。你测试中发现的每一个“模型自作主张”的地方，都值得在文档里加一条约束。
3.3 配套脚本的设计原则：让脚本做“笨重”的事
SKILL.md负责指引，脚本负责执行。我强烈建议在skill中准备好配套脚本，让模型不需要现场写代码就能完成大部分计算。这能极大提升稳定性，因为让大模型写代码处理真实数据文件，每次都可能出现不同的第三方库选择和不同的错误处理逻辑。
我的做法是写一个Python脚本，专门负责数据加载、清洗、计算和报告生成。脚本暴露几个命令行参数，和SKILL.md中的输入参数一一对应：
python generate_monthly_report.py \ --data_file path/to/orders.csv \ --period 2025-06 \ --dimensions province channel脚本内部处理所有数据格式问题和异常情况，输出一份结构化的report.md。SKILL.md里的执行步骤告诉模型只需要做一件事——把用户给的文件路径和相关参数正确传入脚本即可，剩下的全部交给脚本处理。
这样设计有一个额外好处：当数据格式变化时，你只需要更新脚本内的解析逻辑，不需要改SKILL.md的结构；反过来，当业务口径变了，你只需要调整SKILL.md里的规则说明，脚本逻辑基本不用动。两者解耦之后，每一次迭代都更安全，不会牵一发动全身。
设计脚本时还有个原则：脚本不要主动向Agent询问信息，不要设计交互式输入。你无法预知Agent会怎么回答交互问题，很容易卡在等待输入上。所有输入通过命令行参数或配置文件传递，执行完毕后直接以文件形式输出结果，Agent只需要去指定路径读取产出物即可。
3.4 联调验证：不要只看“跑通没跑通”
脚本写好后，我在Agent环境里做了三轮联调。第一轮是“理想输入测试”，我给了Agent一份格式绝对规范的数据文件，命令它生成一份报告。这时候主要看流程是否完整、结果是否有明显错误、SKILL.md里的步骤有没有被跳过的。
第二轮是“脏数据测试”，我在文件里故意加入了一些缺失值、异常格式的日期、重复行，看脚本能否正常处理、SKILL.md里的“缺失比例超过30%需在报告中说明”的规则是否被执行。这轮测试特别重要，因为真实场景中你拿到的数据永远不会像示例那么干净。
第三轮是“描述混淆测试”，我故意问Agent一个和当前skill相关但又不完全等同的问题，比如“能不能帮我把这个季度的毛利也算一下”。这里考察的是模型能不能正确判断“这个任务不完全符合skill的适用范围，不能机械套用”，还是说它会把skill里的流程硬套到一个不该用的场景上。第三轮测试往往能暴露description里的边界描述不够精确的问题，需要回炉修改。
我特别想说一句：联调时不要只盯着“有没有报错”。很多时候程序没报错，但输出的数据是可笑的。比如总计数和明细加总对不上、百分比超过100%、或者报告中出现了原始数据里根本不存在的字段。这些都需要你逐项核对，而不是瞟一眼“运行成功”的返回信息就觉得完事了。
4. 常见问题与排查技巧实录
4.1 模型就是不调用我的Skill，怎么办
这是被问得最多的问题。明明skill文件在库里面，描述也写了几十字，但模型就是在需要的时候视而不见。根据我的排查经验，通常有三个原因。
第一个是description的触发词和用户的实际表达不匹配。比如你的skill是处理“报表”的，描述里写满了“报表”“报告”，但用户问的是“把这个月的数给我拉一下看看”。模型从描述中找不到明确的匹配信号，自然就不会调用。解决办法是把用户可能说的口语化表达也纳入描述，甚至单独写一列“用户可能的说法”示例。
第二个是和system prompt里的其他指令冲突了。比如系统提示里写了“所有数据相关任务都要先检查数据库”，而你的skill描述里没有说明自己也是一种数据处理方式，模型可能优先执行系统层指令，跳过skill。这时候需要在skill正文开头加一句“本skill适用于基于文件的数据分析场景，如果用户指定的是数据库查询，请改用数据库工具。”
第三个是示例太少。模型不是靠读代码来理解skill的，它靠的是“样例”。如果你的SKILL.md里从头到尾没有一句用户提问示例，它很难把抽象描述映射到具体触发场景。我习惯在每个skill里放2到3个“用户输入-你应执行的动作”示例，效果立竿见影。
4.2 多个Skill的描述“打架”了
当你的skill库超过十几个之后，必然会出现描述相似的情况。有一次我同时维护了“周报生成”和“月报生成”两个skill，结果模型经常搞混，用户说要月报，它却触发了周报skill，因为两个description的前半段都是“生成周期性报告”。
我的解决办法是给每个skill增加一个“专属标识符式”的说明，把适用周期和粒度放到description的最前面，并且互相引用反例：“当月报skill不适用（用户只需要近一周数据）时，请考虑使用周报skill。”当skill A的description里主动提到“如果……请转用skill B”，模型对边界判断的准确率会高很多。
这种“skill互指”的做法还有一个好处：它把决策树的一部分直接写进了文档里，模型遇到模糊情况时，可以从描述的互指关系中推出更优的路径，而不是随机选一个。
4.3 脚本执行成功了，但产出结果就是不对
这种问题比脚本直接报错更让人头疼，因为错误是静默的。我最常遇到的是编码问题。Windows环境下生成的CSV文件经常是GBK编码，而Python脚本默认用UTF-8读取，结果是所有中文列名全部乱码，但程序不会报错，只是数据“看起来不对”。
处理办法是在脚本开头显式指定编码，并且通过检测实际编码来适配：
import chardet with open(data_file, 'rb') as f: encoding = chardet.detect(f.read())['encoding'] df = pd.read_csv(data_file, encoding=encoding)另一个典型问题是字段名不一致。用户给的文件里“城市”列有时叫“city”，有时叫“城市”，有时叫“地区”。脚本里写死了字段名就会漏数据。我最后的方案是让脚本启动时先做一次列名标准化映射，把常见别名统一到内部字段名上，找不到的列直接打印警告并在报告中注明，而不是默默忽略。宁可让用户看到警告，也不能让错误数据带着沉默溜过去。
4.4 安全与权限：Skill不是越权工具
聊到后面必须提醒一句——skill的强大之处在于它能指挥Agent做多步操作，但如果权限不受限，这种强大也会变成风险。
我曾经见过有人写了一个skill，描述是“自动登录后台管理系统下载最新数据”，里面甚至直接在脚本里硬编码了账号密码。这种做法非常危险，因为SKILL.md是明文文件，一旦这个skill被复制或分享，凭据就等于公开了。更稳妥的做法是：把敏感凭据放在环境变量或独立配置文件中，脚本通过运行时读取获得，而SKILL.md里只写“从config/credentials.json读取认证信息，不要向用户索要密码”。同时，对需要写文件的skill，尽量限定它的输出目录；对需要联网的skill，明确允许访问的域名范围，防止它被恶意prompt引导去访问不该访问的地址。
另外，skill在执行前一定要有“确认机制”。尤其涉及删除、覆盖、发送类操作时，文档里应当写明“在执行覆盖操作前，必须将原文件先备份到backup目录”。这类保护条款虽然看起来增加了步骤，但在真实生产环境中，它往往就是事故和灾难之间的那层缓冲垫。
4.5 问题排查速查表
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 模型忽视skill直接硬答 | description与用户表达不匹配 | 增加口语化触发词和示例 |
| skill被错误调用 | 多个skill描述相似 | 细化边界，增加反例和互指 |
| 脚本运行结果和预期不符 | 编码、字段名、单位不一致 | 检查数据读取编码、列名映射、手工核对结果文件 |
| 输出内容“看着对”但数据错 | 脚本静默异常 | 为脚本添加警告机制和总量校验 |
| 模型中途跳过步骤 | 执行步骤表述得过于概括 | 拆分步骤，每条尽量包含明确判断和输出物路径 |
| 跨环境运行失败 | 依赖未安装或路径写死 | 脚本开头做环境依赖检查，使用相对路径 |
写在最后的一些心得
如果让我用一个词概括对skills这种机制的感受，我会选“标准化”。它本质上就是给大模型那双“会即兴发挥的手”套上了一套稳定的操作框架。我在这段时间最大的体会是：不要指望模型按照你的模糊意图“猜”出正确操作步骤，你要做的事情就是在SKILL.md里把每一步都钉死，让它既不用猜，也没机会跑偏。
如果你正准备开始用skills，我的建议是别贪多。先挑自己工作中最常做的一件多步骤任务，认真写好第一份SKILL.md，反复测试到它能稳定复现你手动操作的效果，再谈扩展。我刚开始就是一口气写了七八个，结果互相污染、各种误调用，最后又推倒重来。反而是后来老老实实一个一个打磨，效率才真正上来了。
最后分享一个小诀窍：每次在测试中发现模型又“自作主张”了一次，不要骂模型，也不要在系统提示词里加一堆禁止语，而是回去看一眼SKILL.md，问问自己“是不是哪条规则又没写清楚”。把每一次翻车都当作给文档打补丁的机会，迭代十几轮之后，你的skill会慢慢变得像一份滴水不漏的操作规程——到那个时候，你会明显感觉Agent不再是“偶发挥超常的实习生”，而是一个“稳定输出合格成果的熟练工”。
