最近在项目里被 Agent 折腾到差点怀疑人生。模型明明很聪明可一旦让它处理多步任务它就开始抓瞎会写代码但不会先做计划会搜资料但看不懂哪段有用会回答知识库问题但每次都没出处。后来我把一套 Agent Skills 逐步拆开、封装、复用到别的项目里问题才算真正收口。这篇文章会把五个实测最常用的 Skills 完整拆给你看再给一份可以直接照着写自定义 Skill 的教程适合已经跑过 Agent 但总觉得不稳定的开发者也适合刚接触技能体系、想从“单次提示词”走向“可复用能力资产”的人。1. 为什么模型很聪明Agent 却很笨Skills 填了哪个坑1.1 三个让人崩溃的真实现场先说第一个现场。某同事用 Agent 批量整理 200 个项目文件模型写了一段整理脚本第一次运行失败返回报错模型又生成一次还是失败来回折腾了十几轮上下文已经塞满了报错日志最后 Agent 完全分不清哪些是旧日志、哪些是新结果。这不是模型笨而是我们给了它“写代码”的临时指令却没给它“怎么安全地写、写到哪里、如何自检”的结构。第二个现场是知识库问答。给 Agent 接了一个内部文档库它确实能找到相关内容但回答里经常混入模型自己的“知识”。有人问“某配置项现在支持哪些值”它回答出来一个文档里根本不存在的值。原因很简单检索返回了候选片段但模型没有被约束必须引用来源也没被要求“检索不到就说不确定”。第三个现场看似小事但同样烦人周报。每隔两周我都要提醒 Agent“按项目、本周进展、下周计划、风险清单四段输出”稍微换一种问法它又开始自由发挥。每次重新描述规则效果还忽好忽坏前面强调过的东西下一轮就忘。这三个现场指向同一个问题把“怎么做”写在对话里是一次性的把“怎么做”封装成结构化的能力才是可复用的。Agent Skills 要解决的就是这个。1.2 Prompt、工具调用和 Skills 到底差在哪先看一张我常用的对比表形态能不能自己执行跨项目复用开发成本典型问题Prompt提示词模板否需复制粘贴低每次重复灌输容易漂移Function Calling工具调用是需重新注册中粒度太细不会自动组合多步插件体系是部分复用高绑定平台迁移成本高Skill是文档脚本目录即资产中需要写清楚触发条件这个概念有个很直观的类比Prompt 像是每次喊“西红柿鸡蛋要放盐”Function Calling 像是给厨师一把勺子而 Skill 则是给厨师一张完整菜谱——从什么时候做这道菜、怎么备菜、火候怎么控制、出锅前怎么尝都写明白了。模型加载 Skill 时看到的不只是一段文字还包括可以执行的脚本和参考样例。1.3 为什么说 Skill 是目前投入产出比最高的封装方式第一个原因是稳定性。脚本一旦写清楚输出格式就是固定的模型不会再自由发挥字段。第二个原因是可控性。调用前你可以设置开关、白名单、超时比让模型自己去“探索”安全得多。第三个原因是沉淀。一个 Skill 调试好之后可以像工具一样上传给别人用也可以在不同 Agent 之间复用。这也是为什么我推荐有条件的人优先尝试把常用能力做成 Skill。2. 第一个值得封装的 Skill任务拆解器2.1 它处理的是什么问题复杂需求是 Agent 最容易翻车的地方。你让它“把用户反馈按严重程度分级并生成一份处理计划”它不先想清楚边界条件直接开始列处理方案列到一半又发现信息不够再回头问你。更麻烦的是这种执行过程是不可审查的你没法判断它在哪一步的假设出了问题。任务拆解器的思路很直接让 Agent 先把目标拆成一串可执行步骤每个步骤都有依赖关系、验证方式和完成定义然后停下来等人类确认确认之后才真正开始执行。它是在模型“动手”和“动脑”之间加了一道闸门也给了开发者一个干预点。2.2 Skill 的文件结构与触发设计目录结构不需要复杂一个典型版本是这样task-planner/ SKILL.md scripts/ plan.py examples/ sample-input.json sample-output.jsonSKILL.md 开头是元信息模型主要靠 description 里的触发词来决定是否调用所以我会把适用场景写得非常具体而不是只写“任务规划工具”这种模糊描述。--- name: task_planner description: 当用户交给一个需要多个步骤才能完成的目标或需要规划执行顺序、判断并行/串行任务时使用。适合项目启动、故障排查、方案评审等场景。 --- # 任务拆解器使用说明 当你收到复杂目标时不要直接执行。先调用本技能生成计划。 输出格式必须是 JSON包含 - objective原始目标 - steps步骤列表 - step_id编号 - action具体动作 - depends_on依赖的前置步骤 - definition_of_done完成定义 - estimated_time预估耗时 关键规则 1. 每一步必须有可验证的完成定义禁止写“持续推进”这类模糊表述。 2. 能并行的步骤放进 parallel_group。 3. 拆解结束后等待用户确认再继续执行。脚本plan.py本身做得很轻它只负责校验模型生成的计划格式是不是符合上面的 schema如果不合规会返回具体缺了哪些字段。真正做拆解的还是模型但脚本把格式约束住了模型的输出就不会“放飞”。2.3 为什么必须让计划先经过人工确认这一步是我踩过坑之后才加上的。最初版本没有确认闸门模型拆解完直接开干结果它在某一步选择了错误的数据库接口后面所有步骤全白费浪费了十分钟才发现方向错了。加了确认闸门之后这个错误能在 20 秒内被我发现并纠正。对那些需要长期稳定运行的 Agent 场景我建议把确认逻辑做成半自动低风险步骤自动放行高风险步骤强制人工确认。比如读操作可以直接过写操作、删除操作、外部通知操作一律暂停等待确认。风险分级写在 Skill 规则里模型每次调用都能看到。2.4 实测效果在某个测试计划生成的项目里没有拆解器时模型直接开始写测试用例写完的用例东一块西一块覆盖也不全。接入拆解器后它会先列出环境确认、接口清单、用例分组、执行顺序、回归范围每个环节还附带了验证方式。对比下来计划的完整度明显高于手工列的任务清单因为模型会用“依赖”和“完成定义”去倒推有没有遗漏步骤。3. 第二个值得封装的 Skill网页清洗工3.1 为什么直接丢 URL 给模型不靠谱很多开发者觉得模型能上网就能读网页实际上模型拿回的是整个 HTML 渲染后的文本里面混杂导航、广告、页脚、推荐位。你让它提炼一篇文章的核心观点它可能被侧边栏的“大家都在看”干扰把毫不相干的内容当成事实。更浪费的是上下文几篇页面下来token 消耗巨大响应速度肉眼可见地变慢。网页清洗工这个 Skill 解决的是“从 URL 到干净信息”的转换抓取页面、剔除噪音、提取正文、表格最后输出标准 JSON。它是 Agent 做资料调研和情报整理时最基础的底座。3.2 抓取、清洗、结构化三个环节我用 Python 标准库组合实现了一个能跑通大多数静态页面的版本核心思路分三步。第一步是发请求。超时一定要设默认 15 秒失败后按指数退避重试两次。UA用户代理也不要一直用默认值否则很容易被静态站拦截。第二步是解析。优先找 main、article 这类语义标签或者按正文区块的字数和链接密度判断哪些段落是正文。导航区通常链接数量多但文本密度低正好作为过滤依据。第三步是转 Markdown 或 JSON表格单独抽出来。import json import re from urllib.request import Request, urlopen def clean_html_to_markdown(html: str) - str: # 去掉脚本和样式 html re.sub(rscript.*?/script, , html, flagsre.S) html re.sub(rstyle.*?/style, , html, flagsre.S) # 按标题、段落、表格转 Markdown text re.sub(rh[1-6][^]*, lambda m: \n # * int(m.group(0)[2]) , html) text re.sub(rp[^]*, \n, text) text re.sub(rtr[^]*, \n| , text) text re.sub(rtd[^]*, | , text) # 去掉剩余标签 text re.sub(r[^], , text) return text这段代码很简化真实项目里我会在解析前先判断页面编码否则中文页面很容易乱码。判断方式是先看 HTML 头部的 charset如果不存在就用解码探测库猜一遍。碰到动态渲染页面再考虑用无头浏览器但那是少数情况后面单独讲。3.3 能不动用无头浏览器就尽量别动这是我反复强调的一条经验。无头浏览器能解决动态页面问题但代价极大每个页面平均耗时可能从 2 秒涨到 20 秒甚至更久并发一高内存占用直接起飞。实际项目中80% 的页面通过挺简单的 HTTP 请求加解析就能拿到核心正文真正需要完整渲染的是那些用前端框架硬撑起来的网站。我的策略是先用快速请求试一次拿不到有效内容再降到无头浏览器并在 Skill 配置里标记哪些域名可以直接走重策略。3.4 让模型把内容填进固定 Schema清洗完的文本给模型看模型还需要按固定结构整理信息。我会在 Skill 里定义一个输出 Schema要求模型只负责填充不负责发挥。{ title: 标题缺失则为空字符串, author: 作者缺失则为空字符串, publish_date: 原文发布时间没有就不填, content_markdown: 正文 Markdown禁止添加原文没有的内容, tables: [] }这里最关键的规则是字段缺失时填空字符串或空数组不能为了让输出“好看”而编造。这个约束很多人会忽略但它直接决定了后续环节的准确率。下游做知识库入库也好、做情报对比也好最怕的就是模型“润色”过的假数据。4. 第三个值得封装的 Skill代码沙箱4.1 模型最大的毛病是“嘴上跑代码”大模型写代码很像一个自信的实习生它看过很多代码、能说出思路但你不让它真正跑一遍它永远不知道自己的代码在真实环境里能不能通过。我见过太多次模型在对话里笃定地说“这段脚本可以完成批量改名”实际上运行起来连路径拼接都写错了。解决办法只有一个把它生成的代码交给一个隔离的沙箱去跑然后把标准输出、错误堆栈和退出码原样返回给它让它根据真实反馈继续改。4.2 沙箱要保证安全和可复现沙箱是给 Agent 设置的一个“练习场”每次运行都是干净环境跑完就销毁不留下任何状态。默认策略如下参数默认值说明超时时间30 秒超时直接杀死进程防止死循环内存上限2 GB防止异常的大数组或内存泄漏网络访问关闭默认不联网需要时单独开启文件系统只读只能写临时目录不能动宿主文件最大重试次数3 次模型根据报错修复代码最多循环三次运行脚本的核心逻辑不复杂就是把代码写入一个临时文件然后用受限子进程执行捕获 stdout 和 stderr返回 JSON。关键在“受限”两个字默认不允许 shell不继承宿主环境变量工作目录固定在一个临时目录里。import json import subprocess import sys code sys.stdin.read() with open(/tmp/agent_code/run.py, w, encodingutf-8) as f: f.write(code) try: result subprocess.run( [python3, /tmp/agent_code/run.py], capture_outputTrue, textTrue, timeout30, cwd/tmp/agent_code, ) output { exit_code: result.returncode, stdout: result.stdout[-5000:], stderr: result.stderr[-5000:], } except subprocess.TimeoutExpired: output {exit_code: -1, stdout: , stderr: timeout} print(json.dumps(output, ensure_asciiFalse))4.3 自校验闭环是它好用的核心代码沙箱如果只负责“跑一次返回结果”价值并不大。真正让 Agent 变强的是“跑-看结果-改-再跑”的闭环。我会在 Skill 规则里写明如果退出码不是 0模型必须基于 stderr 的报错修复代码然后重新提交执行而不是直接给用户号称“已经完成”。在某个图像处理 Demo 的批量缩放任务里模型第一次跑挂是因为路径写错它看到报错后修正了路径第二次又在输出目录上出错第三次才成功。整个过程没用我干预而如果只在对话里给提示词模型八成会在第一次失败后就开始编一个“看起来成功”的总结糊弄过去。4.4 一些必须提前设置的防护沙箱不是越严格越好太严会让模型任务频繁失败。比如很多脚本要用网络下载资源你直接禁网它就跑不通。我通常按任务类型分级数据分析类脚本禁网网页抓取类脚本允许固定放行目标域名所有写操作一律重定向到临时目录。还有一个容易忽略的点临时目录要定期清理否则跑上一个月就会积累大量垃圾文件磁盘塞满以后沙箱启动都会失败。5. 第四个值得封装的 Skill表格分析师5.1 数据不规整是常态不是例外Agent 处理 CSV、Excel 这类表格数据时最常见的问题是“睁眼瞎”和“凭空编”。模型其实看不到数据文件它只能看到你喂给它的描述如果描述不到位它就会根据经验猜测数据分布然后编出一个看起来合理、实际对不上的统计结论。更麻烦的是真实业务表格从来都不干净日期列有的写“2024/1/3”有的写“2024-01-03”数值列里混着“待确认”这样的文本编码一不小心就是乱码。表格分析师的核心职责是先把文件读取、清洗成标准形态再做字段级画像输出一份数据“体检报告”让模型基于真实统计来回答而不是基于想象。5.2 输出一份不依赖可视化环境的体检报告我设计这个 Skill 时没有让它直接出图表原因是图表依赖具体环境不好通用。我更倾向于让它输出结构化的统计摘要这样模型可以基于摘要写结论也能按需转成 Markdown 表格或文字描述。{ source_file: orders.csv, file_bytes: 1024, total_rows: 1024, columns: [ { name: order_date, dtype: date, missing_rate: 0.01, unique_values: 87, sample: [2024-01-03, 2024-03-12], issues: [存在两种日期格式] } ], warnings: [order_id 存在重复值] }模型拿到这份摘要之后被要求必须先看到 summary 里面的数据才能开始分析。每个结论必须带字段名和计算条件比如“近 30 天订单均值为 X 元”要能对应回 summary 里的字段和过滤条件。这一步就切断了模型自由发挥往回编数据的通道。5.3 处理大文件的第一法则是“别硬塞”有人会把一个十万行的 CSV 直接截断喂给模型这个做法又慢又费 token。正确思路是先做概览再做聚合最后只把聚合结果给模型看。这个 Skill 会默认做三件事检查编码、统计缺失、按关键列做分布概览。碰到超大文件先抽样 1 万行做快速画像再提示用户是否需要用全量数据跑某个聚合指标。5.4 真实案例运营表格的清洗过程某次需要分析订单表的异常情况原始文件里日期列混进了 Excel 自动转换出来的 45231 这类数字格式还有一列金额带有“¥”符号和空格。表格分析师先跑了清洗模块把金额列统一为浮点数把日期列双重解析最后输出的 summary 里明确标出异常值分布。模型据此回答“有 3% 的订单金额为负数可能是退款单”这个结论就是有据可循的而不是看着文件名猜出来的。6. 第五个值得封装的 Skill知识库检索器6.1 裸检索为什么不够给 Agent 接一个内部文档库很多人以为就是“把文档灌进去让模型回答”结果就出现开头说的那种问题模型答得头头是道其实有一半内容是从训练数据里脑补出来的。要避免这个需要把“检索引用”变成强制流程。模型不能凭记忆回答私有知识库问题回答里必须有检索片段的来源编号检索不到就要直说“不知道”而不是绕开。6.2 混合检索 重排是性价比最高的组合知识库检索器这个 Skill 内部通常包含三类能力切片、检索、重排。切片负责把文档拆成适合模型阅读的块同时保留标题层级和原始来源检索负责从知识库里召回候选片段重排负责从上一步粗筛出来的上百个候选中挑出最相关的 5~10 个。我会把检索分成两路一路走关键词匹配适合型号、人名、配置项这类精确词另一路走向量匹配适合“这个模块的失败原因是什么”这类语义问题。两路结果合并后重排效果比任何单一路数都稳定。这个设计说穿了就是让精确匹配兜底让语义匹配负责召回两条腿走路总比单腿稳。6.3 让模型必须带引用回答Skill 规则里最重要的一段约束是这样的如果候选片段的相关度低于阈值模型必须回答“知识库中没有足够信息”并且不能扩展任何未引用内容如果引用要用 [来源编号] 标注同时附上原文片段。我还会在脚本返回的结果里带上每个片段来源文档的路径信息模型引用时直接把路径带出来。某次内部评审原来最大的争议点是 Agent 回答里的某些参数没有出处。换用带引用约束的版本之后每条回答都可以追溯到具体文档段落。评审从“你觉得它说得对不对”变成“它引用的原文是不是准确”这是完全不同的审查层次整个流程的可信度一下子就上来了。6.4 阈值设得太低是灾难很多项目把知识库检索结果直接全量塞给模型哪怕两个片段跟问题毫无关系也一并送进去。模型很容易被不相关片段带偏。我的做法是去掉那些相关度明显低的候选宁可返回片段少一些也不要拿噪音去干扰模型。同时我把它放在 SKILL.md 的“注意事项”里提醒每次调用都要检查是否满足阈值防止模型在信息不足时强行给答案。7. 自定义 Skill 手把手教程从目录结构到调试7.1 先建一个最小可用的骨架自定义 Skill 不需要一步到位我建议大家先从一个能跑通完整链路的最小骨架开始再逐步加细节。标准目录结构一般长这样my-skill/ SKILL.md scripts/ run.py examples/ sample-input.json sample-output.json这个结构里SKILL.md是给模型看的说明书scripts/run.py是真正会被执行的代码examples/给模型提供输入输出样例。别小看 examples 这个目录模型很多时候是靠样例而不是靠文字说明来理解格式的尤其当你要它输出固定 JSON 的时候样例几乎能直接纠正它的格式错误。7.2 SKILL.md 逐行解剖拿一个批量重命名的 Skill 来演示。SKILL.md 的 frontmatter 里写着name和descriptiondescription 决定模型什么情况下调用这个 Skill所以它是整个文件里最重要的一段文字。--- name: batch_file_rename description: 当用户需要批量重命名、批量整理文件名或根据规则统一修改文件扩展名/添加前缀时使用。 --- # 批量文件重命名 ## 适用场景 - 一批文件需要按规则改名 - 文件名存在无规则前缀、后缀、空格等需要清理的情况 ## 操作步骤 1. 收集需要重命名的文件路径列表。 2. 根据用户给的重命名规则生成新旧文件名映射。 3. 执行重命名操作。 4. 输出结果 JSON{renamed: [...], failed: [...]} ## 注意事项 - 重命名前必须输出完整的映射表等待用户确认。 - 禁止覆盖已存在的文件。 - 如果规则不明确先向用户询问不要猜测。这段 Markdown 里写的是给模型看的操作手册。注意描述里那句“等待用户确认”和“禁止覆盖已存在文件”这两个约束如果写在对话提示词里很容易在长对话里被模型忘掉但写在 Skill 说明里每次调用都会被重新加载所以效果稳定得多。7.3 脚本编写规范脚本是 Skill 的执行部分我的经验是尽量让它保持“无状态、自包含”。无状态是指脚本不依赖上一次调用的结果每次调用都把输入完整传入自包含是指脚本所依赖的运行环境要在 SKILL.md 里写清楚比如用什么语言、需要装什么库、从哪里读输入。输入规范我用两种方案轻量任务走标准输入复杂任务走临时文件参数。输出统一是 JSON脚本自身的人类可读日志一律写到标准错误不要混进标准输出。如果不这样做模型会拿到一堆乱七八糟的调试日志当成结果下一次解析直接崩溃。import json import sys data json.load(sys.stdin) print(json.dumps(data, ensure_asciiFalse))这段代码演示了读取标准输入并输出 JSON 的基本流程。真实 Skill 脚本通常会在中间加上逻辑和异常捕获但接口规范保持完全一致。这样做的好处是将来升级脚本、替换脚本都不会影响模型调用方式。7.4 放对位置触发才有效写好 Skill 之后不是放哪都行必须放进 Agent 运行时的技能目录里具体位置可以看平台文档但道理是一样的Skill 加载是可发现的不是靠你把文件路径告诉模型。模型看到的是这个目录下所有 Skill 的 metadata也就是 frontmatter 里的名称和描述因此描述写得准不准直接决定模型会不会在正确时机调用它。测试时我常用一句话验证“给我把当前目录下所有 .log 文件重命名成带当天日期的文件”。如果模型回答“没有可用工具”或试图自己写代码而不是调用 Skill多半是描述里的触发条件没覆盖到用户的原话。这时候要调的不是正文而是 description。7.5 调试 Skill 最常见的问题和处理方式问题可能原因处理办法模型始终不调用 Skilldescription 太抽象没覆盖用户原话增加触发词写清使用场景模型在不需要时误调用描述太宽泛在描述中增加排除条件如“不要用于……”脚本执行失败依赖环境不对或输入格式不符检查运行环境用 sample-input 自测脚本输出格式不符合 Schema模型没看到样例更新 examples 目录或在 SKILL.md 里贴一段标准输出示例Skill 调用后依然乱回答SKILL.md 约束不够显式用“必须”“禁止”写清楚边界这几个问题我几乎每次写新 Skill 都会遇到一轮。尤其是第一个模型不调用 Skill往往不是我脚本写得有问题而是 description 里没有把用户可能说的各种“说法”覆盖进去。用户说“这些文件命名太乱了”和说“按项目名和日期重命名文件”表达方式完全不同但都应该触发同一个 Skill。7.6 让 Skill 能长大多年Skill 开发完成只是第一步我更建议把它纳入版本管理并写一个最小测试。测试可以直接是 shell 脚本构造一个临时目录放几个样例文件调用 Skill 的run.py检查输出 JSON 是否符合预期。这样每次改动代码或者更新描述后都可以先跑一轮回归确认没有破坏已有功能。8. 实测数月之后我对 Skills 的几个真实体会8.1 最值回票价的三个改进我自己的 Agent 项目在接入这套 Skills 之后最明显的改变有三个。第一复杂任务不再失控任务拆解器逼着模型先给方案方案通过后我再放行方向上不会突然跑偏。第二代码相关的输出能验证了模型说要做什么就让代码沙箱跑一遍跑不通它就得继续改而不是拿“应该没问题”来糊弄我。第三知识库回答终于敢拿出去给别人看了每条结论都能追溯到文档再也不用靠“感觉它说得对”来判断。8.2 最大的坑一个 Skill 塞了太多功能我最早做的任务拆解器试图把目标拆解、进度跟踪、风险预警、复盘总结全塞进一个 Skill 里。结果运行起来非常不稳定因为模型拿到手就不知道该先做哪个部分经常跳步骤。后来我把它拆成三个独立 Skill每个 Skill 只负责一件事调用准确率和输出质量都明显回升。这个教训我记到现在Skill 的边界要窄一个 Skill 只解决一个明确问题宁可数量多一点也不要让单个 Skill 变得臃肿。8.3 关于是否会取代提示词Skills 并不会取代提示词它更像是一个让提示词体系化、可复用化的外壳。系统提示词里仍然需要保留全局的行为准则比如语气、安全边界、处理风格而具体的操作流程和经验知识就应该沉淀进 Skill。这样做的最大好处是隔离改一个 Skill 不会影响其他任务的运行而传统提示词模板往往牵一发而动全身。基于我个人的实际使用体验建议你从一个小而实用的 Skill 开始比如批量文件整理或网页正文提取让它先在真实任务里跑通三五次确认稳定以后再逐步扩展。把常用能力逐步变成可积累的技能资产之后你会发现 Agent 的开发开始变得像拼积木而不是每次从零开始教育模型。