Agent技能包：用可复用技能包替代长提示词的工程实践

1. 从提示词到技能包：Agent能力封装的一次升级

最近我一直在折腾团队内部的多智能体协作系统，手里负责的模块，恰好就是标题里这个agent-skills——给大语言模型智能体配置一套可复用的“技能库”。简单说，就是不再把每个任务都硬塞进一条长到离谱的系统提示词里，而是把高频任务拆成一个一个标准化的技能包，让Agent自己去判断“当前这个场景该调用哪个技能”，然后照着技能包里的流程把活干完。

这套思路的收益，在实际项目中比我预想的还要明显。之前我们用单一巨型提示词驱动Agent完成任务，效果很不稳定：换个说法它可能就不知道要干什么了，经常把自己绕进无关细节里，调试一次要翻半天对话。改造为技能包之后，同样的任务类型，稳定性和可复现性都上了一个台阶，排查问题也简单了很多——不用再看整段对话猜它为什么跑偏，直接看它选中了哪个技能、执行到了哪一步就行。

所以这篇东西，我想把整套做法的完整思路、目录结构、落地步骤、踩坑记录和排查经验都整理出来。主要面向两类读者：一类是正在做Agent应用开发，想把行为约束得更稳的工程师；另一类是刚接触这个概念，想搞清楚“技能包”和普通提示词到底有什么区别的产品或技术同学。我会用一个贯穿全过程的实战案例来说明，尽量让看完的人能直接照着搭一套自己的Agent技能库。

1.1 大模型为什么会“眼高手低”

先说一个观察。大语言模型的通识能力确实很吓人，你让它解释什么是“圈复杂度”，它能给你讲得头头是道。但如果你让它“体检一下当前这个代码仓库”，它往往就傻眼了——它没有终端，不会真的去跑命令，也不记得上一轮分析到哪一步了，更不知道你仓库里哪个目录才是真正的源码目录。

我的类比是这样的：大模型像一个知识渊博但手边没有任何工具的实习生。它懂原理，但你让它做菜，它不知道你家厨房在哪、锅碗瓢盆放在哪个柜子里。传统提示词的做法，是把这个“厨房指南”每次都在对话里重新写一遍，又长又容易遗漏。而Agent技能包的做法，是提前把这个厨房的动线、工具的位置、做菜的流程全部整理成一本小手册，Agent要做菜的时候，自己翻到对应那页照着执行。

这个“照着执行”很重要。模型的强项是生成和理解，弱项是保持固定的操作序列。技能包就是用来补偿这个弱项的。

1.2 技能包和普通提示词的本质区别

有人可能会问：技能包不就是一堆提示词吗？我的答案是：形式上有一部分重叠，但定位完全不同。

普通提示词是“一次性指令”，它只对当前这一次对话负责。你换一个类似但不完全相同的任务，就需要重新组织语言、补充背景、写清步骤，而且不同的人写出来的提示词风格天差地别，几乎不可复用。技能包是“可复用封装”，它把一个场景里的最优实践固化下来，统一了格式、补齐了示例、定义了输出标准。技能包之间可以共用底层脚本，可以被动态加载，可以被记录日志，也可以被版本管理。

另一个区别在约束方式上。提示词主要靠“讲道理”，语气软，模型容易跑偏；技能包主要靠“定规矩和给样板”，每一步都有明确的完成标准，做完还有自检，模型没有太多自由发挥的空间。举个例子，让模型“检查一下这段代码质量”是一句提示词，它可能给你输出一段泛泛而谈的评论。但如果给它一个repo-inspector技能包，它就明确知道要先跑哪些统计脚本、要按照哪些维度打分、最后要填进哪个报告模板里。

1.3 技能包里的“三件套”：入口、流程、自检

用了这么久，我总结一个合格的技能包至少要包含三样东西，缺一不可。

第一是入口，也就是这个技能的描述、触发条件和适用场景。它决定了Agent在什么情况下会选中这个技能。入口写得含糊，模型要么看不见它，要么乱用它。

第二是流程，也就是完成这个任务需要经过哪些具体步骤。流程要尽量原子化，每一步都应该是“可以验证做没做”的动作，而不是“深入分析一下”这种无法检验的空话。

第三是自检，也就是任务完成的判断标准。比如输出结果里必须包含哪些字段、报告格式必须符合哪个模板、某些关键指标算不出来的时候要怎么标注。没有自检，Agent很可能跑完全部流程，产出一份模型自己觉得行了、但人类根本没法用的结果。

这三件套在我的所有技能包里都是固定的骨架，后面我会结合例子拆开细讲。

2. 动手之前：技能体系的整体设计思路

很多人在做技能包的时候，第一反应是“先把目录建起来，把文件写出来”。我自己的经验是，动手前把设计思路想清楚，后面能少返工一半。技能体系不是代码库，不是文件越多越好，也不是技能越多Agent就越聪明，关键是把工程做对。

2.1 技能粒度：太细会碎，太粗会糊

技能粒度是我踩得最深的一个坑。最开始我习惯把技能拆得很小，比如“统计代码行数”“计算圈复杂度”“统计提交频率”，每个都单独做成一个技能包。结果Agent在处理真实任务的时候，需要连续调用五六个小技能才能完成一次体检，上下文被占掉一大块，中间只要有一个技能选择错了，整个任务就断掉。

后来我换了个思路：一个技能应该对应一个“可以独立交付的成果”。我不管它内部用多少脚本、分几个阶段，只要它执行完能交出一份完整的结果，那这个粒度就是合适的。按这个标准，代码体检就是技能，代码行数统计只是体检里的一个步骤。反过来，粒度也不能太粗。我试过把整个“代码质量评审”做成一个技能包，结果Agent拿到之后完全不知道从哪里开始，流程里塞了十几个步骤，每一步它都只能靠猜。权衡下来，最简单实用的判断标准就是：这个技能的输入是否明确、输出是否明确、执行完是否有一个可以作为下一次任务输入的产物。

2.2 技能目录与文件组织

目录结构这事，网上说法很多，我自己在实际项目中用下来，固定的组织方式能显著降低维护成本。目前我们团队约定俗成的一套目录长这样：

repo-inspector/ SKILL.md scripts/ analyze_complexity.py analyze_duplication.py collect_git_stats.py templates/ report_template.md issue_template.md examples/ example_input_1.md example_output_1.md

每个技能包单独一个文件夹，入口统一叫SKILL.md，脚本、模板、示例各自放进对应子目录。这样做的原因很朴素：脚本跟着技能走，技能发布的时候连同脚本一起带走，不会出现“这个技能依赖另一个目录里的脚本”这种脆弱关系。模板单独放，是因为有些技能会生成很长的报告，模板要是和说明全塞在一个文件里，文件会变得非常大，加载和阅读体验都很差。示例单独放则是为了让运行时可以按需加载——不是所有示例都要在每次执行时进入上下文，而是只在“需要对照参考”的时候取出来。

2.3 技能描述要怎么写，模型才认得准

这是整个技能体系里最容易被低估的部分。模型做技能选择的时候，本质上是把用户的表达和所有技能包的描述做语义匹配。你的描述写得像一篇论文摘要，模型读起来费劲；写得像商品标题，模型一看就知道这东西是干嘛的。

我总结了一个“好描述”的公式：一句话说明技能做什么，两句话说输入输出，三句列出典型触发场景，最后明确排除不适用的情况。举两个对比的例子。

糟糕的描述：“分析代码仓库并生成报告。”这话说了等于没说，Model不知道它分析什么指标，也不知道报告长什么样，更不知道和另外几个分析类技能有什么区别。

我推荐写这种风格：

description: | 对代码仓库执行体检，统计圈复杂度、重复率、提交频率等质量指标， 输出一份结构化的体检报告。适用于代码评审前、版本发布前、接手旧项目 快速摸底等场景。当用户提到“仓库体检”“复杂度”“代码质量报告”“评审前检查” 时优先选择。不要用于单文件级别的格式修正或语法检查。

这段描述把“能做什么”“输入输出是什么”“什么时候用”“什么时候别用”全说清了，模型在做意图匹配时，几乎不会选错。我把触发场景单独用引号标出来，是因为模型对“具体的短语”比对“抽象的分类”敏感得多。

2.4 单文件还是多文件：按“是否可复用”来分

另有一个很实际的问题：一个技能到底该是一个SKILL.md就完事，还是应该拆成多文件？我见过有人把十几页的说明全塞进一个文件，也见过一个只有3行逻辑的技能也要建四个目录，两种都极端。

我的判断标准是：这个技能除了“让模型生成文本”之外，是否需要外部资源参与。如果技能纯粹靠模型推理就能完成，比如写摘要、翻译、风格改写、生成测试用例，那一个SKILL.md就够了，写太复杂反而增加加载成本。如果技能需要跑脚本、读模板、执行外部命令，比如仓库体检、自动部署、数据分析，那就必须多文件，把脚本和模板独立出来，让流程说明只负责“指挥”，而不是让模型对着几百行代码“想象”结果。

还有一个判断点是复用性。如果脚本和模板可以被多个技能共用，那它们更合适提升为一个独立模块，而不是躺在某个技能目录里。如果只是某个技能自己的内部工具，那就老老实实放在这个技能包里。

3. 核心实操：从零搭建一个可复用的技能包

下面进入正题，手把手搭一个技能包。我用“代码仓库体检”作为贯穿全过程的例子，因为它有清晰的输入输出、有外部命令调用、有可验证的产物，非常适合演示技能包的完整生命周期。

3.1 选一个真实场景做拆解

场景需求来自一个很常见的痛点：接手一个老旧项目之前，想快速知道这个仓库质量到底怎么样，技术债严重不严重，团队最近还在不在维护。这个需求听起来很大，但仔细一拆，其实可以拆成几步：先把仓库拉下来，然后统计基础的规模信息，接着算复杂度、重复率等静态指标，再看看近期提交频率和活跃度，最后把所有数据汇总成一份报告。

拆解的时候要特别注意“完成标准”。比如“统计复杂度”这个步骤，完成标准不是“模型说了一句复杂度偏高”，而是“跑完复杂度统计脚本，拿到了每个文件的数值，并和阈值做了对比”。拆到这一步，你才能把手感从“让模型想”变成“让模型做和算”。

3.2 创建目录与元信息

第一步，建目录和SKILL.md里的元信息头。我习惯在文件里放一段YAML格式的元数据，因为这些字段会被调度器解析，用来做技能索引和选择。

--- name: repo-inspector description: | 对代码仓库执行体检，统计圈复杂度、重复率、提交频率等质量指标， 输出一份结构化的体检报告。适用于代码评审前、版本发布前、接手旧项目 快速摸底等场景。当用户提到“仓库体检”“复杂度”“代码质量报告”“评审前检查” 时优先选择。不要用于单文件级别的格式修正或语法检查。 version: 0.1.0 trigger_keywords: 仓库体检, 复杂度, 代码质量, 评审前检查, 技术债 parameters: repo_path: type: string description: 仓库本地路径或远程URL，必填 depth: type: string enum: [quick, standard, deep] default: standard description: 分析深度，quick只做快速指标，standard全量分析 ---

注意description字段，它会出现在Agent的技能清单里，并且会被拿去和用户意图做匹配。所以这里写的每个词都尽量贴近真实用户可能使用的表达。parameters字段也很重要，它告诉调度器这个技能需要哪些参数，调度器就能提前从对话里抽取，而不是等模型去问用户。

3.3 把主流程写成可校验的清单

元信息下面是技能的核心，也就是主流程。我强烈建议把流程写成“可校验清单”的样式，而不是一段连续的散文。散文式说明模型读起来轻松，但步骤边界模糊，它容易跳过关键环节。清单式说明每个步骤都隔离出来，模型自然会一步步走。

我的repo-inspector的流程部分是这样写的：

# 执行流程 1. 环境准备 - 检查repo_path是否存在且有读权限 - 如果repo_path是远程URL，先执行clone到本地临时目录 - 确认本地具备执行Python脚本的环境，缺失依赖时先安装 2. 数据采集 - 运行 collect_git_stats.py，收集最近90天提交频率、活跃贡献者数 - 运行 analyze_complexity.py，统计各文件圈复杂度 - 运行 analyze_duplication.py，统计重复代码率 3. 指标计算 - 根据阈值表，把原始指标换算成健康度评分（0-100） - 对得分异常的文件，标记为待关注项 4. 报告生成 - 从templates/report_template.md读取报告模板 - 按模板填充各维度结果 - 在报告末尾列出待关注文件和优化建议 # 完成标准 - 报告包含以下字段：仓库规模、复杂度评分、重复率评分、活跃度评分、待关注文件清单 - 任一指标无法计算时，在报告中明确标注“无法计算”，禁止编造数值 - 报告输出完整，不遗漏任何一节模板字段

这里最关键的变化在“完成标准”。有了它，Agent执行完之后还能自己检查一遍产物，不满足条件就重跑对应步骤。这个自检机制，是最能显著降低模型“空转”的设计。

3.4 用示例给模型“打个样”

大模型是典型的少样本学习者，有的时候给它一个贴脸的示例，比给一百句解释都管用。技能包里我建议至少放一组输入和输出的对照示例，让模型知道“用户说出类似的话→技能执行完→产出长这样”。

示例文件example_input_1.md可以很简短：

用户请求： 帮我看看当前这个项目目录的代码质量，快要发版了，我想快速过一遍。

对应的example_output_1.md其实就是一份按模板填好的报告样例，开头长这样：

# 代码仓库体检报告 - 仓库路径: /data/projects/demo - 分析深度: standard - 报告时间: 2025-01-10 ## 整体评分 - 复杂度健康度: 72/100 - 重复率健康度: 81/100 - 活跃度评分: 65/100 ## 待关注文件 | 文件 | 圈复杂度 | 问题 | | --- | --- | --- |

写示例的时候，我会刻意让用户表达不那么“理想化”。真实用户很少会按照技能描述里的名词说话，他们会说“快发版了帮我过一遍”“这个项目能不能接”“老项目值不值得维护”。这些表达都该进示例。模型看到“用户说X，技能产出Y”的配对，下次遇到相似请求，命中率会明显好过只靠语义匹配。

3.5 注册进技能清单

技能包写完后，要让它能被调度器发现。我们通常会维护一个全局的技能清单，类似这样一个manifest文件：

{ "skills": [ { "name": "repo-inspector", "summary": "代码仓库体检：输出复杂度、重复率、活跃度结构化报告", "keywords": ["体检", "复杂度", "代码质量", "发版评审", "技术债"], "path": "skills/repo-inspector/SKILL.md", "version": "0.1.0" } ] }

注意这里的summary字段非常短，因为Agent在选择技能时，这一行摘要会和其他技能的一行摘要排在一起，模型先做粗筛，选中后再加载完整的SKILL.md进入上下文。摘要写得好不好，直接决定粗筛的准确率。我见过有人把整个description塞进summary，结果把所有技能的摘要都拉得很长，模型看三行就晕了。

3.6 测三次，再谈上线

技能包上线前，我至少会做三类测试。第一类是直接命中的表达，比如“帮我体检一下 /data/projects/demo”，预期是选中repo-inspector；第二类是间接命中的表达，比如“这个老项目还能不能继续开发”，预期也应该选到它；第三类是不该触发的表达，比如“帮我把这个文件格式改一下”，绝对不能选中repo-inspector。

测试的时候重点看两个指标：技能选择准确率和最终产物合规率。如果准确率不够，回头改description和示例；如果合规率不够，回头改流程和完成标准。我用真实项目跑了三轮测试，才把整体成功率从六成左右拉到接近九成，中间改得最多的不是代码，而是描述和示例，这个比例大家心里要有数。

4. 技能调用链路上的那些关键细节

技能包本身写好了，不等于系统就能稳定跑起来。调用链路里的上下文管理、技能协同、执行日志这些工程细节，才是决定实际体验的隐藏变量。

4.1 一次完整的技能调用长什么样

我拆过一遍完整的调用链路，大致是六个环节：

1. 意图识别：把用户输入转成结构化请求，抽取可能的参数（仓库路径、分析深度）。
2. 技能选择：调度器把请求和所有技能摘要做匹配，选出得分最高的技能。
3. 技能加载：把选中的SKILL.md、相关示例、脚本路径注入上下文。
4. 计划生成：模型根据技能流程生成执行计划，确定调用哪些脚本、什么顺序。
5. 执行阶段：调度器调用工具或脚本，把真实执行结果回传给模型。
6. 结果汇总：模型把脚本输出填入模板，做自检，输出最终报告。

这六个环节里，最容易出错的是第4步和第5步的交接。模型生成的“计划”不能只是自然语言，最好是一种结构化指令，比如“运行脚本A，参数为X，输出写到Y路径”，调度器才能正确翻译成真正的命令。我在流程说明里会明确写上“每一步执行前，先输出准备执行的命令及预期产物”，这样交接的歧义会小很多。

4.2 上下文管理：不能把所有技能一股脑塞进去

技能多了之后，一个最大的挑战是上下文窗口的有限性。如果系统里有二十个技能包，每个包加载进来都要占几千token，模型很快就没精力处理真正的任务了。

我们的做法是“分层加载”。最外层是全局技能清单，每个技能只保留一行摘要和关键词；模型粗筛之后，只把top-1或top-2的技能完整加载进上下文；技能内部又有示例按需加载的机制，不是每次都要把三个示例全读进去，而是根据任务类型加载最相关的一组。这样即使技能库扩大到几十个，单次任务占用的上下文也不会明显增长。

我建议把技能文件的总体积控制在一个经验范围内：SKILL.md不超过五千字，示例单个不超过两千字，元信息描述不超过两百字。超过这个范围，加载成本和模型的理解成本都会陡增，效果反而下降。

4.3 多技能协同：让Agent学会“先查后做”

单一技能能解决的问题有限，实际项目里常遇到需要几个技能接力的情况。比如一次体检之后，用户可能还想看到“具体怎么修复这些问题”，这时候就需要先跑repo-inspector，再把报告结果喂给另一个“修复建议生成”技能。

多技能协同最大的坑是：Agent容易跳步，体检报告还没生成就直接跳到提建议，导致建议内容空泛。解法是把协同关系写进技能描述。我在修复建议生成技能的描述里会写出“仅当已获取仓库体检报告后使用；如尚未体检，先调用repo-inspector获取报告”，这一句话就解决了大半的跳步问题。关键的中间产物，比如体检报告，我会要求Agent输出成独立文件或结构化JSON，而不是只存在对话记忆里。这样下一个技能读文件就行，不需要从上文的只言片语里拼凑信息。

5. 常见问题与排查技巧实录

这块是实践里最值钱的部分。我把自己真正踩过、并且确认有解的坑列出来，每个都带排查思路，希望帮后来者少走点弯路。

5.1 模型一直不调用技能，问题出在哪

遇到过好几次：技能包写好了，注册也注册了，用户输入也明显是对着的，可Agent就是不调用，反而用自己“想象”的能力硬答。排查下来，八成问题出在描述和用户表达的语义距离太大。我有个技能描述里写的是“技术债评估”，但用户现实中会说“这项目还有救吗”，语义虽然相近，但模型在实际匹配时未必能打通这层关系。解法是给description加上更口语化的触发表达，同时补一组真实用户说法的示例。如果还不行，再看技能摘要里的关键词是否覆盖了高频用词。

5.2 技能老被误用，怎么限定边界

技能多起来之后，误用比不调用更让人头疼。最典型的是“仓库体检”和“代码格式化”两个技能抢同一个输入。用户说“帮我弄一下代码质量”，两个技能听着都合适。解法是在描述里写清排除条件，比如仓库体检的技能描述里明确写“不要用于单文件级别的格式修正或语法检查”，代码格式化技能里则写“仅处理明确的单文件或单目录格式化请求，不进行质量评估”。边界写清楚了，模型自然就不会乱选。排查误用的时候，我会打开技能选择日志，看模型为什么选中了它，把日志里诱因对应的那句描述改写掉，比盲目改阈值有效得多。

5.3 执行到一半就崩，流程为什么断

流程断裂，是这个系统最常见的稳定性问题。我遇到过一个案例：技能流程有八步，模型执行到第五步之后直接跳到报告生成，把中间两个统计步骤“脑补”完了。原因不是它偷懒，而是流程步骤太密，模型需要在上下文里保持的信息太多，它为了减负就自动跳步，而且它自己意识不到缺步骤。

解法是双管齐下。第一，把流程里的每一步做得更“原子化”，并且每一步的产物都要明确，比如“运行脚本后必须记录返回值”，模型就很难糊弄过去。第二，在关键节点设置“完成校验”，执行到下一步之前，先检查上一步的产物是否存在且符合预期。另外一个是工程级的方案：把脚本执行这类操作交给调度器而不是模型本身。模型只负责“决定跑哪个脚本、把结果填到哪里”，真正跑脚本是工具完成的，这样模型既不会跳步，也不会“想象”出统计数据。

5.4 输出忽好忽坏，基本是缺了一个东西

如果技能执行成功率还行，但输出格式时好时坏——有时多了个章节，有时少了个字段——那基本可以断定是模板约束不够。光在流程里写“按模板生成报告”是不够的，模型有自己的审美，它总想加点自己觉得有价值的内容。解法是给模板加上“字段级约束”，比如在report_template.md里用注释标注“字段不可缺，顺序不可调换，禁止新增章节”，并且在SKILL.md的完成标准里明确列出必含字段清单。实测下来，模板字段约束越死，输出稳定性越强，哪怕报告看起来没那么“聪明”，至少它是可用的、可解析的。

5.5 排查速查表

6. 踩坑之后，我对技能设计的三条原则

项目做下来，我自己总结了三句话，权当这次经验的收尾。

第一句是“边界先于内容”。技能包最大的价值不在于写得多详细，而在于让模型知道什么时候用它、什么时候不用它。两个技能的描述里把边界写清楚，比各自堆砌五千字都管用。

第二句是“示例大于解释”。与其在流程里反复写“请输出列表格式的报告”，不如直接把一个填好的样例报告放在它面前，模型看一眼就会照着做。语言层面的约束力，远没有样例层面的感染力强。

第三句是“先跑通再优化”。第一个技能包别一上来就追求完美，找一个小场景、跑通一遍完整调用链路、确认产出物可用，比停留在设计文档里推演半年都有价值。稳定性的提升是一个个迭代累积出来的。

另外，这套技能包体系我后续还在继续扩展，方向大概包括技能版本管理——给每个技能加上变更记录，跟踪行为漂移；还有团队内的技能共享库，让大家把高频好用的技能沉淀成公共资产。如果你也在做Agent相关的事情，强烈建议从今天开始挑一个高频任务，试着把它变成一个技能包，跑通一遍，体会会非常不一样。