前阵子朋友圈和各个技术群里都在聊 agent-skills一开始我觉得这就是把 prompt 拆成文件管理而已没太当回事。直到我自己在一个真实的数据处理任务里被一个超长系统提示词反复折腾到想砸电脑才彻底明白把经验沉淀成 Agent 可复用的技能包不是换一种管理方式的问题而是 Agent 应用能不能规模化的分水岭。这篇不打算复述某个产品的新功能介绍我想认真讲讲我搭建一套 Agent 技能体系时的完整思考技能到底该设计到多细、目录文件怎么组织、Agent 靠什么机制自动发现技能、以及亲手踩过的几个典型坑。如果你正在做 AI Agent 开发或者想把自己的工作流开放成其他人也能复用的技能这篇应该能给你省下不少弯路。1. 从“超长提示词”到“技能包”的转变Agent 真正缺的是什么1.1 大提示词方案在真实任务里是怎么失控的早期我做的 Agent 应用基本都是“大 Prompt 引擎”路线把所有业务规则、输出格式、参考示例、工具调用逻辑全部塞进系统提示词靠模型强大的长文本理解能力硬扛。Demo 阶段这招确实爽改个规则跟在大字符串里动刀一样画面里演示得漂漂亮亮的。但到了真实任务阶段问题一个接一个。首先是上下文稀缺性问题系统提示词占掉几千 token用户真实输入的空间就被压缩模型开始把精力分散在理解冗长的规则上反而不关心用户的核心诉求。其次是排障成本超过 1000 行以后每动一个标点你都不敢大意因为你永远不知道模型是根据哪一段话来理解规则的回归测试成本高得吓人。我自己遇到过最离谱的一次给 Agent 写了 1200 多行的系统提示词包含各种规则、格式模板、异常分支。结果在一个多轮任务中模型直接把历史对话里聊天内容当成原始数据拿来处理输出结果全乱套。排查到最后问题根源竟然只是某一段关于“历史记录”的说明出现了歧义。那次之后我就下定决心一定要把提示词里的业务流程拆出去用独立的技能模块承载经验。1.2 技能模块的实质把隐性经验变成可加载的显性模块好那“Agent 技能”到底是什么。以目前主流 Agent Skills 生态里的常见设计为例一个技能包通常就是一个自带结构说明的目录。目录名是技能名称目录里面放一个 SKILL.md 作为技能说明书说明书开头用 YAML frontmatter 写技能的名称和描述正文是给 Agent 看的详细操作指南。技能用到的脚本、模板、依赖声明全放在同一个目录里跟着技能一起走。Agent 在启动或运行过程中会收到一份技能库清单。当用户提出目标时一个技能选择机制会根据描述和目标的相关度把最匹配的 SKILL.md 内容动态注入到上下文里。模型读完这份说明书就知道该调用哪个脚本、按什么顺序执行、遇到异常怎么处理就好像临时拿到了一份带工具的任务手册。这个机制最大的价值在于它把过去散落在模型记忆力里的经验沉淀成一个一个独立的、可版本化的模块。团队新成员可以直接读 SKILL.md 学习一个技能的使用方法改一个技能时也只影响引用它的场景。想想以前光靠对话让模型学会一套复杂的文件处理流程每换一个 session 就要重新培训一次现在技能一加载过程线直接就回来了。1.3 技能、工具函数、工作流别把三层混成一层这里想团队内部一个比较重要的认知对齐技能不是工具的替代品也不是工作流引擎换个名字。三者解决的问题层次完全不一样。我平时喜欢用一个比喻工具是一个稳定的汽车变速箱技能是维修手册加工具箱的组合工作流则是整条运输线路的调度计划。维度工具函数Tool技能包Skill工作流Workflow解决问题单次函数调用完整任务执行方法多任务编排与决策是否需要模型推理少按参数执行即可多需要理解场景与异常中流程固化但有人工触点可复用粒度接口级任务级流程级典型载体OpenAPI、MCP ToolSKILL.md 脚本资源编排引擎、元技能适用场景获取数据、调用服务格式转换、组合脚本、定制报告需审批、多人协作、跨应用理解这个分层之后你就不会出现“这个功能是不是用一个技能搞定”的困惑。功能调用就拆成工具任务流程就做成技能多步骤的运营流程交给工作流或元技能来编排三个层次配合使用边界才清晰。2. 动手设计技能前先想清楚这几条边界2.1 什么任务适合做成技能什么任务要重新考虑做了一段时间技能沉淀我总结出一条筛选标准一个任务适不适合做成技能看它是不是“流程相对固定但执行过程需要大量判断”。比如把一份 PDF 转成结构化 Markdown——流程固定吧但中间要判断页面里哪些是表格、哪些是正文、哪些需要 OCR这种场景就非常适合技能化。再比如“根据销售数据生成周报”格式是固定的但每一周的数据情况不一样模型需要挑选指标、判断异常、决定怎么渲染图表这也是典型技能场景。反过来如果是“输入两个参数返回一个结果”这种纯接口调用做成技能就多余了。任何有清晰入参出参、不需要过多决策流的操作都应该直接做成 Tool 或 MCP Tool。我之前就犯过错误把一个数据库查询封装成了技能结果模型每次都要通过说明文本来理解该调用哪个脚本明明一条 function call 就能搞定的事情活生生多消耗了几百 token还增加了出错概率。另外还有一个很容易被忽略的陷阱凡是需要人在每个环节做最终决策的任务都不适合直接技能化。比如“自动给客户发送邮件并确认回复”这种中间可能涉及公司审批、客户隐私确认你在技能里写再多的规则模型也没办法替人拍板。这种任务硬往技能里塞最后出来的效果一定是不伦不类管理层也不敢真的放权。2.2 我心中的好技能五个可以直接照做的标准经过反复重构我现在要求团队里每个技能包必须同时满足下面五个条件名称唯一且语义明确。技能名全部用连字符小写比如extract-tables-from-pdf一眼能看出用途。绝对不允许util1、cleaner这种名字模型根本猜不到该在什么时候调用。描述面向模型检索。描述要写成“当用户需要……时使用”这种触发式句子而不是“一个高效的数据清洗工具”。两个描述在人类眼里差别不大在模型选择器里差别天差地远。输入输出边界清晰。SKILL.md 里必须写明输入参数、产出物、响应状态码以及常见的失败原因。模型不会读你的代码它全靠这份说明来理解脚本行为。依赖自包含。技能脚本所需的所有第三方库、工具、模型都要在技能目录内声明清楚。不能假装环境里什么都有。可测试可观测。每个技能跑完后必须有明确的日志输出和返回状态模型才能判断下一步是继续还是要报错。这五个条件不是花架子。第一个条件和第二个条件决定了 Agent 能不能在正确时机引用技能第三第四个条件决定了引用了能不能稳定执行第五个条件决定了出错了能不能迅速定位。我见过太多技能包写得很漂亮但模型执行时完全不知道脚本输出的是什么状态最后只能强行猜一猜就崩。2.3 两个最容易踩的反模式万能技能与模糊命名新手第一次做技能库十有八九会掉进同一个坑想做一个“处理所有文档”的万能技能。PPT、PDF、Word、Excel 全往里塞方法写了一大堆功能覆盖极广。但实际用起来效果非常差。原因很简单技能选择靠的是描述和目标之间的语义匹配。当多个任务挤在一个技能里描述只能写成又长又泛的大杂烩模型每次匹配都像是在大商场里找一个没有标牌的小店不是完全找不到就是找错楼层。正确做法是拆成一个个独立的小技能每个技能专注一个过程表格提取是一个技能文档格式转换是一个技能摘要生成是一个技能。每个技能的小体积、高清晰度整体组合起来的覆盖面反而更大。技能库就像工具箱任何一个工具箱里如果全是一把能拧所有螺丝的瑞士军刀那绝不是好事板手、扳手、套筒该分开就要分开。另一个反模式是命名随意。早期我把一个技能叫process_data几个月后自己都忘了它到底是清洗数据还是生成指标。后来团队明确规定每一个新技能进库之前必须先在全局技能清单里搜索一遍确认没有同名、近义描述的其他技能。名字是给模型看的也是给人类维护者看的模糊命名的代价短期看不见等技能库超过 20 个的时候就会集中爆发。3. 搭建一套可复用的技能库目录、文档与脚本的实战细节3.1 整个技能库应该长什么样一个能够长期演进的技能库我建议从一开始就用仓库模式来组织千万不要在项目里随便堆一堆 Markdown。以下是我的 agent-skills 项目重构后的目录布局你可以直接抄agent-skills/ ├── skills/ │ ├── extract-tables-from-pdf/ │ │ ├── SKILL.md │ │ ├── extract.py │ │ └── requirements.txt │ ├── merge-sales-reports/ │ │ ├── SKILL.md │ │ ├── merge.py │ │ └── templates/ │ └── meta-skills/ │ └── monthly-report-pipeline/ │ └── SKILL.md ├── tests/ ├── prompts/ └── docs/为什么单独建一个meta-skills目录因为元技能本身也是一个技能但它不直接执行脚本而是负责把多个基础技能编排成完整工作流。把元技能单独分类存放能够避免模型在选择阶段把一个“组织任务”的技能和一个“执行任务”的技能混为一谈。这个微小区分在技能数量上来以后对命中率的提升非常明显。tests目录放的是每个技能对应的样例输入和期望输出docs目录放的是给人类团队看的说明文档prompts目录放的是系统提示词片段。这样一来技能、测试、文档是三层独立结构各自的演进节奏完全不一样不会互相阻塞。3.2 SKILL.md 的结构与写法是说明书不是功能简介SKILL.md 是 Agent 理解技能的唯一入口写得不好脚本写得再漂亮也白搭。一份合格的 SKILL.md 必须包含 frontmatter 和正文两部分。frontmatter 承担元数据正文是行动指南。下面是我项目里的一个实际例子--- name: extract-tables-from-pdf description: 当用户需要从 PDF 文档中提取表格数据并输出为 CSV 或 Excel 时使用。适用于包含大面积表格的 PDF例如财报、统计报表、合同附件。如果 PDF 本身是扫描图片且无可复制文本必须依赖 OCR 能力如果用户只需要提取文字而非表格请改用其他技能。 --- # Extract Tables from PDF ## 适用场景 - 输入PDF 文件路径或 URL - 输出CSV 格式的表格数据输出到用户指定目录 ## 执行步骤 1. 确认输入 PDF 存在运行 python extract.py input.pdf output.csv 2. 脚本自动检测页面横线边界对扫描件自动调用 OCR 进行文字识别 3. 脚本返回状态码0 表示成功1 表示表格无法识别2 表示输入文件不存在 ## 注意事项 - 表格超过 50 行时输出文件会自动拆分避免单个文件过大 - 若页面中表格横跨两页脚本会尝试拼接但拼接失败时不要静默跳过必须输出告警有几个写作重点值得强调。描述里面要写清楚“什么时候不能用”这比写“什么时候能用”更重要。模型做技能选择时本质上是在做判断你把排除条件写清楚了它就不会在用户只是想要一段普通文本时强行触发技能转换。正文部分要按行动顺序组织而不是按功能模块组织。模型执行技能时像在按流程单操作你给它一份按模块写的数据字典它还得自己拼装执行顺序多一层推理就多一层出错风险。3.3 技术依赖与路径问题技能自包含的工程细节技能最容易翻车的地方就是依赖环境。写技能脚本的人往往会假设“机器上应该装了什么”但这种假设上线后一定会出问题。技能库里的每个脚本我要求它必须自带依赖声明并在入口处做显式检查。我举个实际例子一个技能脚本的开头通常长这样python -c import pandas 2/dev/null || { echo 依赖缺失: pandas; exit 3; }这一段的作用很直接依赖缺了立刻用状态码 3 告诉 Agent 当前环境不满足条件而不是让脚本在运行时输出一堆莫名其妙的 Traceback最后模型错误地认为任务是数据处理逻辑失败。另外所有文件路径都通过参数传入不允许脚本读取环境变量来猜路径。Agent 是严格按照 SKILL.md 的说明来执行命令的如果命令参数不确定它会犹豫甚至自行脑补脑补的后果等于脚本的行为不可复现。对于复杂的技能我还会在技能目录里单独维护一个requirements.txt并在 SKILL.md 的依赖小节里注明安装命令。现在很多技能库还支持requirements.txt中指定额外的 pip 索引源这一点对内部环境特别有用。团队里的新成员复制技能库时一条命令就能把环境搭好而不是逐个问老员工“你那儿怎么跑通的”。3.4 技能的回归测试与版本管理把它当代码对待很多人会觉得技能不就是一个给模型看的文档和几个脚本没必要做测试这个想法迟早会让你栽跟头。我曾经有一次只是改了一个技能描述里示例路径写法脚本一行没动结果在真实 Agent 任务里模型按新描述传了一个不存在的输出目录任务反复报错。就是因为描述和脚本行为没有做同步验证一个小小的不一致让 Agent 完全误解了脚本的预期行为。所以我后来强制规定每个技能都有一组固定样例输入和对应的 expected outputs任何修改无论改的是脚本还是文档都必须重新跑一遍这组测试。测试不用做得很复杂一个简单的测试目录加一个检查脚本就够了。我用的就是基础的 pytest每个技能对应一个测试用例验证输入、执行、输出、退出码四个环节。设定越简单越不容易被绕过你要设计成每次都要敲长命令保证你坚持不了一周。版本管理方面技能库的每次变更使用语义化版本号技能本身用目录名固化路径但允许在 frontmatter 里标注版本。技能发布到仓库后不能再随便原地修改线上版本而是要发布新版本目录。原因是 Agent 的缓存机制很可能会导致旧版本 SKILL.md 还留在上下文中假如你原地修改它执行时会发生新旧行为混合排错极其困难。4. Agent 如何找到并调用技能自动发现机制与描述工程4.1 一个经常被忽略的假设模型真的会看你的技能库吗很多人在本地搭好技能库跑通 demo 之后就以为万事大吉了但实际他们忽略了一个根本假设Agent 不会天然知道你技能库里有什么。在主流 Agent 框架的实现里启动时系统会读取技能库清单并把技能列表交给一个技能选择机制。这个机制可能是模型本身也可能是一个单独的技能评分模型但不管具体实现是什么它依赖的核心信息都只有一个技能描述与用户当前目标的语义相关度。这句话翻译成大白话就是你的 Agent 在做技能选择的一瞬间拿到的不是完整的 SKILL.md 全部内容而是每个技能的“标题加描述”这样一个迷你摘要。如果技能描述本身写得像产品新闻稿没有任何可触发的场景词那模型根本不会在正确时机想起这个技能。这不是模型能力不够而是你提供给它的检索信息质量不够。这也解释了为什么我反复强调描述工程的重要性。你不能把技能库想象成一个“带目录的百科全书”而要把它想象成一个“面向检索的搜索引擎索引”。Index 里的每一条内容都要为被准确命中而写作。4.2 把描述写成触发条件一个真实的命中率对比我手里有一个项目开发了两个技能一个是把文字笔记转成清单另一个是从会议纪要里提取行动项。最初的 description 写得很“正规”类似“A note conversion tool”和“An action item extraction utility”。实测结果Agent 经常在用户只是随便写一段想法的时候直接触发了笔记转换技能因为它看到“note”这个词就觉得命中。而会议纪要提取技能反而在用户明确要求“从纪要里拉出待办”时犹豫不决。后来我把两个技能的描述全部重写了一遍。笔记转换技能改成“当用户明确要求将笔记内容整理成有序清单、待办事项或步骤列表时使用若用户只是在记录想法、写草稿没有提出整理要求绝对不要使用。”会议纪要技能改成“当用户提供会议记录、访谈稿或多人对话文本并要求提取可执行的行动项、负责人与截止日期时使用若用户只是要求概括要点不要使用。”改了描述之后触发精准度提升非常明显。道理其实不复杂模型做技能选择时更像一个快速的分类判断而不是深度阅读。它在有限上下文里看到描述中的“明确要求”和“绝对不要”会显著降低误触发的概率。给技能写描述类似在仓库每个箱子上贴标签标签上必须写清楚里面有什么、什么时候来取而不是写“优质好物”这种空话。4.3 元技能把细粒度技能编排成完整工作流基础技能越拆越细Agent 在复杂任务里反而会懵。今天让它生成月度报告它要自己去想应该先调用清洗技能再调用指标计算技能最后调用模板渲染技能。这个过程让模型自由发挥也行但每次都发挥得不一样输出风格很不稳定。解决方案就是用元技能Meta Skill做编排。元技能本身也是一个 SKILL.md只是它不执行任何脚本它的正文是给 Agent 的流程指令。我最常用的元技能写法是用编号任务清单描述完整流水线不用任何图表就清清楚楚列步骤。比如一个做月度销售简报的元技能正文是这样第一步调用parse-sales-data技能把原始销售表转换为统一字段的中间数据文件。第二步调用extract-trends技能基于中间数据计算同比、环比并输出要点摘要。第三步调用render-docx-report技能将摘要和图表渲染为可阅读的月度报告。元技能让基础技能可以设计得更加“笨”和单一不必考虑与其他技能的组合关系只需要把单一职责做到极致。模型在执行元技能时像项目经理一样按清单调度各个基础技能每一步之间传递文件任务边界清晰任何一步失败都可以精确回溯到具体技能而不是怪罪“模型理解不对”。我强烈建议技能库超过十个之后就开始设计元技能层这是让技能体系真正能支撑复杂业务的关键一环。5. 上线之后常见的三个故障我踩过的真实坑和处理记录5.1 技能明明加载了Agent 却“装看不见”技能库第一次试点上线时我确认系统日志里已经把所有技能文件读取成功技能列表也出现在上下文中。然而真实对话里Agent 几乎一个技能都不用所有任务都靠自己的记忆直接回答。排查了很久最后发现原因让我哭笑不得技能描述里写的是“你可以使用此技能”而系统提示词里没有引导模型优先考虑技能。对模型来说“可以”代表可选项不强制一旦任务路径稍微有点复杂它就直接跳过技能凭已有的知识泛化回答。解决办法是在系统提示词里加了一条优先级规则当任务与已加载技能匹配时默认按技能流程执行而不是直接给用户结论同时要求模型在输出中标记技能调用痕迹。这个改动之后技能使用率立刻上来了。这个细节非常关键尤其是从 Demo 到上线的阶段很多人跑通但翻车原因就出在这里。你可以理解为给模型一个工具箱放在它旁边它可能懒得用你得告诉它二选一命题——要么开箱取工具要么给出不用工具的理由。5.2 技能描述互相打架选择漂移的典型表现技能数量超过 15 个以后我开始遇到一个新的问题多个技能描述越来越接近。比如既有extract-tables-from-pdf又有convert-pdf-to-docx当用户说“帮我处理一下这个 PDF”模型会在两个技能之间犹豫甚至随机挑一个输出结果当然不稳定。解决这个问题我没有用复杂算法而是从流程上做限制每新增一个技能之前先全文搜索现有技能库确认没有描述重叠。如果新技能是一个旧技能的扩展我就拆掉旧的升级成一个元技能来覆盖完整流程如果两个技能确实功能不同但描述容易混淆我就必须在双方的 description 里显式加上对照说明。例如在extract-tables-from-pdf的描述里加一句“如果用户需要保留 PDF 的排版并转成 Word 文档请改用 convert-pdf-to-docx 技能”反向也写一条。让模型在选择时能够通过排除法锁定正确目标。5.3 本地能跑沙箱里就是跑不通环境不一致问题技能里的脚本经常出现一个窘境本地运行一切正常交给 Agent 的沙箱环境后开始莫名失败。我第一次排查时花了大半个小时最后发现脚本默认使用系统的 Python而沙箱里的 Python 路径不同几个依赖包也没有安装。这个坑特别隐蔽因为脚本在本地环境下根本不会暴露路径和依赖问题。后来我把所有技能脚本统一改成在入口处做两件事第一显式检查关键依赖是否可用不可用则立即输出状态码并退出第二脚本中用相对路径或者由外部传入绝对路径定位文件和资源绝不依赖进程当前工作目录。因为 Agent 调用技能时并不保证工作目录是你的技能目录脚本如果写死了相对路径一定会在某个环境里崩掉。把环境差异前置到可以排查的状态故障定位时间直接从半小时级别降到了几分钟。5.4 技能与 MCP 工具的边界约定最后再提一个架构层面的坑。如果你的 Agent 既挂了 MCP 服务器又配了技能库两者之间一定要有优先级约定。MCP 工具提供的是稳定、可连接的 API 能力适合做实时数据获取和外部服务调用技能则更适合模型引导的流程处理和格式转换。假如你在技能里也写了一遍数据库查询逻辑而这个查询 MCP 工具已经能实现模型就会面临两个入口选择时极易混乱。我对两个体系做了事权划分一切能通过 MCP 低成本拿到的外部数据和接口能力都交给 MCP技能专注在流程编排、格式转换、数据清洗、文档渲染这种需要理解上下文的环节。技能里出现外部系统调用逻辑时优先写作“调用 MCP 工具xx获取数据”而不是自己重新写一份接入代码。这样划分以后模型既不会重复造轮子也不会因为两套工具语义冲突而选择困难。按我这几个月的折腾经验做 Agent 技能体系最关键的一点是把“技能”当作项目里的一等公民来对待有目录、有文档、有测试、有版本而不是简单地把几段 prompt 存成文件。技能写得越清晰Agent 的表现就越稳定团队维护起来也越省心。最后分享一个小技巧技能库根目录维护一个 INDEX.md把全部技能的名称、用途、所属元技能列成一张总表让模型在开始检索之前先获得全局视角能够显著降低误选率。如果你也在搭自己的 agent-skills希望这篇能帮你少走几步弯路。