在本地计算机上装了二十多个 Skill 之后我发现自己越来越不愿意用它们了。表面现象是“工具越多越乱”想让 Agent 按指定格式生成周报它偏要调用另一个做 Git 分析的 Skill想让 AI 写一段符合团队风格的代码它却先念了一遍所有 Skill 的说明文件。真正的问题不是安装数量太多而是 Skill 集合缺少工程治理。本文会从 AI Agent 场景中的 Skill 机制出发拆解“多装反而难用”的原因给出诊断、设计、清理和测试的方法帮助你把 Skill 从“越堆越重的包袱”变回“随时可用的能力包”。1. 为什么 Skill 越多Agent 反而越“笨”1.1 Skill 是什么为什么需要按“能力包”组织在 AI 编程助手和 Agent 场景里Skill 可以理解为一个被预先封装好的“能力包”。它与普通指令提示词的区别在于Skill 通常包含说明文件、使用示例、脚本模板和必要的配置信息Agent 可以在需要时按名称或描述召回它而不是每次通过对话临时解释一遍“应该怎么做”。可以把 Agent 看成执行者把 Skill 看成工具箱里的工具。Agent 决定调用哪个工具而工具本身承载“怎么把这件事做好”的经验。比如日志分析 Skill 负责接收日志文件路径输出异常归类结果周报生成 Skill 负责读取 Git 提交记录和任务清单输出结构化周报。这里要区分 Skill 和 AgentAgent 是任务规划和执行的载体Skill 是 Agent 可复用的能力单元。一个 Agent 可以挂多个 Skill同一个 Skill 也可以被不同 Agent 使用。装 Skill 的本质不是让模型变得更强而是让模型更大概率调用到一个“提前写好流程、示例和边界”的能力包。1.2 上下文膨胀每个 Skill 都是一份潜在上下文占用当 Agent 判断“当前任务需要某个技能”时它通常要读取 Skill 的描述有时候还要读取完整的 Skill 内容。这带来的直接问题是Skill 越多Agent 在决策阶段需要扫描的内容就越多。装一个 Skill 时上下文可能只增加几百个 token感觉不出来。当 Skill 数量增加到 10 个以上并且每个 Skill 都写了冗长的说明、大量示例、多段历史修改记录时Agent 在每次对话开始或工具调用前都可能被动加载一部分 Skill 元数据。结果是两个首轮响应变慢因为需要处理更多候选内容。关键信息被稀释Agent 用更多“精力”去排除不相关的 Skill而不是直接完成任务。更隐蔽的开销是“任务描述”和“Skill 描述”的匹配精度下降。如果 5 个 Skill 都包含“生成报告”这四个字Agent 就要做更细的意图判断。这个判断本身不是零成本的一旦判断出错后面所有步骤都建立在错误的工具选择上。1.3 召回冲突多个 Skill 的描述互相覆盖很多 Skill 难用不是因为代码写错而是“元信息”写得太差。比如下面三类描述在真实项目里非常常见描述只写“这是一个报告生成工具”没写适合什么输入、什么场景、什么输出格式。两个 Skill 都声称自己能“分析日志”但一个擅长 Nginx 访问日志一个擅长 Java 异常堆栈。命名含义模糊比如tool_utils、helper、my_skillAgent 根本无法从名字判断用途。当多个 Skill 的召回条件重叠时Agent 的选择会出现不稳定同一个任务这次选了 A下次选了 B。这不是模型“随机的”而是描述相似度过高模型无法根据当前上下文区分出更优解。解决召回冲突的关键是为每个 Skill 写出“排除条件”不只写它擅长什么还要写它不擅长什么。比如“本 Skill 用于分析 JVM 崩溃日志不处理网络抓包文件”。这样 Agent 在意图边界更清楚时才能减少误用。1.4 副作用和依赖Skill 变成了不可控的黑盒对比“一段提示词”Skill 的另一个特点是它可以包含脚本、命令和文件读写操作。这让 Skill 更像一个程序但也引入程序常见的问题依赖外部命令或环境变量换个机器就失效。会修改文件、调用网络接口、执行 shell 命令但没有声明副作用。错误处理不完整中间步骤失败后Agent 只能用很模糊的错误信息继续尝试。版本更新后行为改变但没有变更记录旧任务直接失败。装 Skill 容易维护 Skill 难。如果一个 Skill 在关键时刻执行了错误的命令、覆盖了配置文件、生成了不符合规范的代码那么它造成的负面影响比不装还大。生产环境里使用 Skill 时必须像对待第三方依赖一样看待它知道它做什么、它能碰什么、它不能碰什么。2. 先诊断怎么知道当前 Skill 集合哪里出了问题2.1 记录 Agent 每次实际选用了哪个 Skill想优化 Skill 集合不能只靠“感觉哪个好用”。第一步是观察 Agent 在每个任务里到底调用了哪些 Skill调用顺序是什么结果是否成功。如果所用工具本身有会话日志可以直接搜索“Skill 名称”或“tool call”等关键字。没有日志时可以在 Skill 的脚本入口写一行输出到固定日志文件。例如在 Skill 脚本里增加echo [skill] $(date %Y-%m-%d %H:%M:%S) skillweek-report task$1 /tmp/skill_usage.log这样运行一段时间后就能得到真实调用记录而不是依赖主观记忆。接下来把记录整理成一张表格用于评估每个 Skill 的使用情况Skill 名称被调用次数成功次数失败次数被误用次数平均响应耗时week-report12102115slog-analyzer312430s2.2 从四个指标判断 Skill 的健康度单个 Skill 值得留下需要满足四个基本指标命中率在适合调用它的任务里Agent 有多大比例真的调用了它。命中率低说明描述或元信息不清晰。成功率调用之后任务是否按预期完成。成功率低说明 Skill 内部流程、示例或依赖有问题。误用率Agent 在明显不相关的任务里调用了它。误用率高说明描述太宽泛缺少排除条件。资源消耗加载和执行 Skill 带来的 token 消耗、响应时间和外部副作用。资源消耗高但收益低应该精简或移除。实际项目中建议优先关注“高误用率”和“低命中率”因为它们直接暴露 Skill 选型层面的问题。成功率低则多数是编写质量问题可以通过补示例、改脚本解决。2.3 把“体感慢”变成可量化的数据如果整套 Skill 用起来很慢需要区分是“加载慢”“选择慢”还是“执行慢”。一种简单的测量方法是分别记录三个阶段的时间Agent 收到任务后到第一次调用 Skill 的时间。Skill 内部脚本运行的时间。Skill 脚本产生输出后Agent 生成最终回答的时间。针对第一阶段变慢可以尝试减少候选 Skill 数量或给高频 Skill 设置更简洁的 description。针对第二阶段变慢要检查脚本是否执行了不必要的网络请求、是否编译程序、是否读取了大文件。针对第三阶段变慢常见原因是 Skill 输出太冗长Agent 需要重新提取关键信息改进方式是在 Skill 内完成数据聚合只返回结构化摘要。2.4 十项审计清单对现有 Skill 做一次体检时可以按下面清单逐项检查是否每个 Skill 都只做一件事。是否有明确输入和输出格式。描述是否包含使用场景和排除场景。是否包含可直接复用的示例。是否包含失败处理和边界说明。是否依赖当前环境独有的路径、端口、密钥。是否声明了权限和副作用。是否有版本号能否判断当前内容更新时间。是否与另一个 Skill 功能重叠。是否被过去 30 天的真实调用记录证明有效。如果某一项不满足应该先修正再继续使用。审计结束后把不合格的 Skill 暂时禁用而不是马上删掉这样可以观察 Agent 的调用行为是否改善。3. 用最小案例看清 Skill 变慢和误用的链路3.1 一个看似正常的 Skill 文件下面是一个“项目周报生成” Skill 的简化示例。先不要看它哪里好而是观察它哪里可能引发问题--- name: weekly-report description: 生成项目周报汇总 Git 提交记录、任务完成情况和风险项。 version: 1.0.0 tags: [report, git, team] --- # Weekly Report Skill 你需要生成一份团队周报输出为 Markdown 格式。 ## 步骤 1. 获取 Git 提交记录。 2. 汇总本周完成的任务。 3. 输出周报。这个 Skill 结构看起来完整但实际使用时可能踩很多坑。description 没有说明“输入是仓库路径还是任务清单”也没说明“输出文件保存到哪里”。步骤三个词太少Agent 可能自由发挥导致每次输出格式都不一样。缺少示例Agent 不知道“风险项”应该写多细。最致命的是如果目录里还有另一个 Skill 写着“汇总本周成果”两个 Skill 就可能同时被召回。3.2 为什么会选错描述和任务意图的匹配当用户说“帮我写个项目进展”Agent 会同时看到weekly-report、meeting-summary、todo-planner等 Skill。如果每个 Skill 的描述都有“项目”“分析”“报告”这类词模型就需要猜。给出更精确的描述能显著减少误选description: 从 Git 仓库读取本周提交记录按功能模块汇总为团队周报输出 Markdown 表格。 当用户要求「本周周报」「项目进度汇总」「按 Git 提交生成周报」时使用。 不处理会议纪要不做代码审查不生成日报。这段描述做了三件事说明输入来源Git 仓库。说明输出格式Markdown 表格。说明边界不处理会议纪要不做代码审查。Agent 做工具选择时是通过描述语义匹配当前用户意图的。要让描述具备可判断性就要主动告诉它“不要做什么”。这是降低误用率最有效的手段。3.3 为什么调用后输出不稳定示例不足和缺少验证仍以周报 Skill 为例如果步骤写得过于抽象Agent 可能输出非常“飘”的内容。比如把“风险项”写成一堆空话“需要关注整体进度风险”却不列出具体是哪个需求、阻塞在哪。这不是模型能力问题而是 Skill 没有告诉它“什么叫合格输出”。改进方式是增加输入样例、处理步骤和输出反例## 输入示例 repo_path: /data/project/order-center date_range: 2025-05-12 到 2025-05-18 ## 合格输出示例 本周重点 - 订单列表接口超时优化优化后 P99 从 850ms 降到 400ms。 - 完成支付回调重试机制设计。 风险项 - 订单导出功能依赖的报表服务未上线阻塞联调计划 5 月 20 日拉通。 下周计划 - 接入新版本 Redis 客户端验证连接池参数。## 不合格输出示例 本周重点完成订单优化。风险项需要注意性能。给反例是非常重要的。模型在生成阶段会参考 Skill 里的示例分布如果只有输入没有输出就缺少“风格锚点”。放一个不合格输出作为对比能有效抑制 Agent 写出泛泛而谈的周报。3.4 最小修复收敛职责、增加自检当我实际修复类似 Skill 时会同时做四步改 description加入输入和边界。删除与主题无关的“额外建议”段落。增加一个可运行的脚本把 Git 提交记录预处理成结构化 JSON而不是让模型自己去读原始日志。在 Step 最后加入自检项生成结果必须包含“完成内容”“风险项”“计划”三部分否则重新输出。这个最小修复例子说明了一个原则Skill 不能只靠“告诉模型做什么”还要尽量把确定性步骤用脚本做掉只把需要模型判断的工作留给 LLM。4. 如何设计一个“装了不后悔”的 Skill4.1 单一职责一个 Skill 只解决一类问题设计 Skill 时最容易犯的错误是“什么都往里装”。比如一个名为dev-tools的 Skill 同时包含代码规范检查、Git 提交、部署脚本、日志查看。表面上是提高复用实际上会让 Agent 在召回时无法判断“当前任务到底属于这个 Skill 的哪个能力”。推荐做法是拆成独立 Skillcode-review-rules按照团队规范检查本次改动。git-commit-helper根据 diff 生成符合 Conventional Commits 的提交信息。log-analyzer分析指定日志文件并输出异常摘要。拆分会增加文件数量但每个 Skill 的体积更小、意图更清晰。学习环境里可以先用一个“万能 Skill”做验证生产环境一定要按职责拆分否则后续维护成本会快速增长。4.2 最小权限与显式输入输出一个 Skill 是否安全要看它被 Agent 调用时能碰哪些资源。尽量避免在 Skill 里写入“你可以执行任何 shell 命令”这种宽泛授权。相反应在说明文件里声明允许执行的具体命令和路径范围。## 权限声明 - 允许读取仓库根目录下的 git log。 - 允许读取 reports/ 目录。 - 禁止修改 src/ 下的源代码。 - 禁止访问外部网络。这里真正的理由是Agent 是概率模型它在执行步骤时可能因为上下文影响做出意外决策。显式声明权限和副作用等于给 Skill 加了安全边界。输入和输出也要显式定义输入仓库路径、日期范围、输出目录。输出Markdown 文件路径以及可直接粘贴到群里的摘要文本。错误输出当输入路径不存在时返回可理解的中文错误提示。4.3 用元数据和标签做好“可检索性”Skill 的元数据是 Agent 召回的重要依据。需要关注的核心字段包括字段作用编写建议name唯一标识使用短横线命名如weekly-reportdescription召回和判断的核心写清输入、输出、场景、反例tags辅助分类控制在 3 到 5 个避免泛词version变更追溯每次修改递增author责任归属方便团队排查问题dependencies外部依赖列出需要提前安装的命令和版本有些工具的 Skill 元数据格式是 YAML Frontmatter有的是 JSON、TOML。无论使用哪种格式原则是一样的让 Agent 在低 token 成本下快速判断这个 Skill 是否匹配当前任务。4.4 给 Agent 写示例和反例商品说明需要“使用说明”Skill 也需要面向 Agent 写使用说明。最关键的两个部分是“合格输出示例”和“错误行为反例”。合格输出的作用是固定格式。明确信息颗粒度。提供语气和术语参考。错误行为反例的作用是告诉模型“不要生成这种内容”。缩小模型的搜索空间。显著减少后期人工修正。一个比较完整的 Skill 正文结构可以是一句话定义 Skill 目标。输入参数。执行步骤。合格输出示例。不合格输出反例。错误处理和注意事项。版本更新记录。4.5 版本管理和测试Skill 也要回归将 Skill 当作代码来管理至少要建立两个习惯第一使用 Git 管理 Skill 目录。每次改动都要有 commit message避免“最近改了但不知道改了什么”。第二准备一个冒烟测试目录。里面放固定输入和预期输出运行 Skill 后比对结果。比如日志分析 Skill 的测试输入是samples/error.log预期输出包含特定异常类名和出现次数。改动后运行一遍冒烟测试能快速发现回归。5. Skill 库治理从“堆积”到“分层管理”5.1 按使用频率和风险分层把所有 Skill 平铺在一个目录里必然导致难以选择。可以按两个维度分层使用频率高频、中频、低频。风险等级只读、可写文件、可执行命令、可访问网络。分层之后目录结构可以是skills/ core/ # 高频且低风险如 git-commit-helper project/ # 项目专用如 weekly-report admin/ # 中低频但权限较高如 deploy-helper archive/ # 已禁用或待删除的 Skill不是所有 Skill 都需要被 Agent 随时看到。低频高风险 Skill 一旦被误用代价很大所以应尽量设置为“需要显式确认”后才调用而不是默认候选。5.2 命名规范和目录结构常见的命名规范有两种能力命名log-analyzer、database-backup-check适合能独立复用的小工具。场景命名project-standup、incident-report适合和特定业务流程绑定的 Skill。命名建议使用小写短横线避免空格、中文和首字母大写。目录结构则以“按工具分类再按业务区分”为宜skills/ git/ commit-message/ branch-cleanup/ report/ weekly-report/ incident-report/ data/ csv-inspector/ api-response-analyze/这样做的原因是Agent 以及编写者在查找、调试、批量导入导出时都能更快定位目标文件。5.3 学习环境与生产环境不要一套 Skill 通用学习环境里可以大胆试验把各种候选 Skill 放进去跑但生产环境必须区分。学习环境下允许装大量实验性 Skill。使用“只有一条提示词”的极简雏形。允许脚本写得比较随意。不关心权限和副作用。生产环境建议只保留被真实调用记录验证过的 Skill。锁定 Skill 版本升级前做回归。收敛权限不允许 Skill 随意修改源码。增加调用日志和监控出现误用时能快速定位。很多团队“Skill 越装越难用”根源是把学习环境的堆积直接搬到了生产环境。正确路径是先在实验环境验证再对 Skill 做“生产化改造”最后才发布到生产环境的候选列表里。5.4 定期清理哪类 Skill 该删判断一个 Skill 是否该删除可以用三个问题过去 30 天内是否被调用过被调用后是否真的完成了任务是否有能力相近且表现更好的替代品满足条件“未调用且没有明确使用计划”“调用后频繁失败”“与其他 Skill 重叠度超过 70%”的就直接移入 archive。归档不是删除而是把候选列表体积降下来。如果 30 天后确认不需要再彻底归档或删除。6. 常见坑和排查路径6.1 五个高频问题及处理问题现象常见原因检查方式处理建议Agent 完全不调用某个 Skilldescription 太模糊或太长查看候选 Skill 的元信息重写描述加入场景关键词和边界Agent 调用了错误的 Skill多个 Skill 描述重叠对比所有 Skill 的 description增加排除条件拆分职责调用后结果时好时坏示例不足或步骤太抽象修改输入并运行多次增加合格输出示例和反例调用后脚本报错依赖环境不一致在干净环境运行脚本在 Skill 中声明依赖并做启动检查修改 Skill 后不生效工具缓存或未重新加载查看工具文档确认加载机制重启会话或重新加载 Skill 列表6.2 排查顺序为什么 Agent 没调用我的 Skill如果 Agent 一直忽略你精心写的 Skill按下面的顺序排查确认 Skill 是否在正确的目录且被当前会话加载。确认 description 里是否出现用户描述中可能出现的关键词。确认 description 不是“复读机式开发”比如只说“编写报告”而不说输入输出。观察日志中 Agent 是否看到了这个 Skill。如果工具支持调试模式开启后能看到候选列表。如果候选列表里压根没有说明加载或检索环节失效如果候选列表里有但没选说明描述竞争不过其他 Skill。最容易忽略的是“候选列表存在但描述竞争失败”。这种情况需要对比同类 Skill 的描述让目标 Skill 的表达更贴近用户常用语并减少其他 Skill 的泛化描述。6.3 排查顺序为什么调用后结果不对调用后结果不对要区分是“理解不对”还是“执行不对”。理解不对Agent 误解了输入参数。查看输入示例和参数说明是否清晰。执行不对脚本或命令失败。手动在终端运行一遍 Skill 内部脚本观察错误输出。输出不对步骤执行成功但最终回复不符合要求。检查合格输出示例是否足够具体。一个有效的做法是让 Skill 先输出中间结果例如先打印读取到的 Git 提交列表再生成周报。这样出现问题时能判断是哪一步出错而不是只看到“周报格式不对”的模糊表现。6.4 排查顺序为什么变慢遇到整套 Skill 响应明显变慢时按照以下顺序定位先确认是不是网络或模型服务本身变慢。最简单的方式是关掉所有 Skill 后执行同一个任务。如果关闭所有 Skill 后正常再二分禁用一半 Skill找到拖慢响应的那一批。定位到具体 Skill 后检查其正文长度、内置示例数量、脚本执行耗时。对比“长文本说明版”和“精简说明版”的响应时间保留效果和效率的平衡点。实际项目里经常发现慢的根源是某个 Skill 的正文包含大量重复历史信息或者示例过长。这类内容可以移到单独文件只在需要时按引用读取。7. 最佳实践清单让 Skill 从“难用”回到“好用”7.1 发布一个 Skill 前的检查清单每次新建或更新 Skill 前建议逐项检查只做一件事。有明确输入和输出。description 包含场景关键词和排除条件。包含至少一个合格输出示例。包含至少一个不合格输出反例。不含硬编码的绝对路径、端口、密钥。声明了依赖和权限。有版本号和最近更新日期。在测试目录中跑通了冒烟用例。不会和其他 Skill 产生明显功能重叠。这份清单可以作为团队 Review Skill 时的最小验收标准。凡是不过关的 Skill先不进主目录。7.2 日常使用习惯不要一次装几十个 Skill。可以先用 3 到 5 个验证流程再按需增加。每次任务结束后花 10 秒记录“是否调对 Skill”。长期记录比“感觉好用”更可靠。遇到 Agent 误用某个 Skill当天就修改其 description 或边界不要攒到月底。把使用频率极低的 Skill 移出候选目录而不是直接删除方便日后恢复。7.3 团队协作变更记录和责任归属团队使用 Skill 时要把它们当作共享代码来维护每个 Skill 目录下放一个CHANGELOG.md记录每次修改的内容和原因。使用 Git 分支管理不要在主干上直接调试。引入“Skill Owner”概念一个 Skill 至少指定一个负责人。收到“不好用”反馈后先定位是召回问题、脚本问题还是示例问题再决定修改方向。7.4 扩展方向从“单个 Skill”到“能力编排”当 Skill 数量可控且稳定后下一步可以考虑能力编排。比如日志分析 Skill 的输出可以直接作为周报生成 Skill 的输入。这种编排能减少重复描述也让每个 Skill 的职责更单一。在编排时要注意格式契约A Skill 的输出结构要被 B Skill 明确解析因此定义 JSON Schema 或 Markdown 模板比自由文本更可靠。长期来看Skill 不仅是“给 AI 看的说明书”更应是一套模块化、可测试、可观测的工程资产。回到最初的问题Skill 越装越多为什么越来越难用并不是 AI 变笨了而是 Skill 集合没有随数量增长同步升级设计质量。只要用工程思维去治理 Skill 库从描述、职责、示例、权限、测试和清理几个方向持续迭代Skill 数量再多也能保持清晰和可控。建议下一次动手前先给现有 Skill 做一次审计删掉那些“看似有用却从未被正确调用”的能力包。你会发现少即是多。