你有没有遇到过这样的情况为了让 AI Agent 显得更“专业”你往它的 Skill 库里塞了十几个精心设计的 Skill——覆盖代码审查、数据库设计、日志分析、UI 还原、数学建模……结果它反而连最简单的任务都要绕一大圈甚至把日志分析当成代码生成任务给你一段完全不相关的输出。这不是段子而是 Agent 进入生产环境后越来越常见的现象。当大家默认“Skill 越多Agent 越强”时实际结果往往是Skill 越多Agent 越笨。问题的关键不在于模型变弱了而在于我们不假思索地把 Agent 当成一个“只要喂够技能就能变聪明”的容器。这篇文章先给结论再拆解背后的机制最后给出一套工程化的 Skill 治理方案。无论你是在用自家框架做 Agent还是在折腾主流编码 Agent 工具的 Skill 功能这篇文章都值得读完。1. 先说结论Skill 数量与 Agent 能力是倒 U 型关系先抛一个核心判断Skill 数量和 Agent 的实际表现不是线性正相关更接近“倒 U 型曲线”。开始加 Skill 时Agent 确实会变强。因为模型默认缺乏领域知识你给它补充编码规范、日志分析方法论、接口设计约定它能明显少犯低级错误。但一旦 Skill 多到一定程度收益开始递减接着迅速转为负收益。为什么会出现“越多越笨”从工程层面看原因很直白Agent 每次决策都要从 Skill 候选里挑一个匹配的选项越多选错概率越高Skill 的元数据不管有没有被调用很多框架都需要将其注入到上下文里这会持续挤占模型可用的有效信息空间Skill 与 Skill 之间还会产生指令冲突模型同时看到多种“最佳实践”时容易失去主线。很多团队确实没有量化过这个曲线但从社区反馈和工程直觉来看这条曲线普遍存在。它背后的解释并不神秘模型的上下文窗口是有限的模型的选择能力也是有限的。你给 Skill 库加内容本质上是在给 Agent 增加信息熵而不是单纯增加“智商”。如果你发现某个 Agent 在加入多个新 Skill 后开始答非所问最该怀疑的不是模型参数而是你的 Skill 库设计。2. Skill 到底是什么从提示词工程到能力插件化要理解 Skill 为什么会产生负面影响先要确认它的定义。Skill 是一段可复用的、被 Agent 按需加载的任务执行方案。它通常包含一组指令、领域知识、代码片段甚至脚本资源。Agent 收到用户请求后根据请求意图和 Skill 的描述决定要不要调用某一个 Skill。一个典型的 Skill 目录结构可能是这样的skills/ ├── generate-api-client/ │ ├── SKILL.md │ └── scripts/ │ └── generate.py ├── analyze-nginx-log/ │ ├── SKILL.md │ └── templates/ │ └── report.tpl └── generate-sql/ ├── SKILL.md └── examples/ └── order-detail.sql其中SKILL.md是核心它定义了 Skill 的元信息和执行步骤。不同 Agent 框架的文件格式可能不同但核心字段基本都是name和description用来让模型在决策时理解“这个 Skill 是干什么的”。你可以把 Skill 理解为一种“模板化、可复用的任务执行方案”。它和普通 Prompt 的区别在于普通 Prompt 是一次性的写在主提示词里每次都参与推理Skill 是模块化的可以独立维护、复用、版本化核心信息进入上下文详细内容按需加载。它和 MCP Tool 的区别更明显MCP Tool 是 Agent 与外部系统交互的通道作用是“打通外部世界”Skill 是 Agent 内部的“行为手册”作用是“告诉模型遇到某类任务时按什么步骤走”。一句话总结MCP 是手Skill 是操作手册。听起来很美好问题恰恰出在“按需加载”这四个字上。模型怎么判断该不该加载某个 Skill它必须先“看到”所有 Skill 的描述然后从中选择。选择本身就是最大的风险点。3. Skill 越多越笨的四个核心机制这一部分进入正题。抛开情绪和猜测从机制层面分析 Skill 数量为什么会拖垮 Agent 的表现。3.1 上下文窗口再大也经不起元数据轰炸很多大模型的上下文窗口已经做到 200K 甚至更多于是有人觉得“多塞几个 Skill 描述没多少钱”。这是误解。上下文窗口越大损失不是越少而是更容易被无关内容稀释注意力。Skill 入库后它的名字和描述通常会被注入到系统提示词或 Agent 的候选列表中。比如你有 30 个 Skill每个描述 100 字也要 3000 字。再加上 Skill 的前置说明、触发条件和使用示例很容易塞进去 8000 到 10000 字。这些内容不是白白占地方而是会干扰模型对关键信息的注意力。当你真正想让 Agent 理解一段用户需求时它可能正在同时评估“这个需求该匹配哪个 Skill”可用注意力被切走了一部分。有人会反问那我用检索式 Skill 库不把全部元数据注入行不行行但检索不是万能的。检索本身会引入新的错误源如果查询向量和候选 Skill 描述向量彼此接近Top-k 就可能选出错误技能。3.2 相关性选择像是在拥挤市场里找人模型要决定用哪个 Skill本质上是做一次意图匹配把“用户当前请求”与“候选 Skill 描述”做相似度排序选择最匹配的那一个。当候选集合小的时候这个排序比较稳定。技能 A 描述清晰技能 B 边界明确模型很容易选出正确答案。但 Skill 数量增多后候选描述之间的相似度会上升analyze-nginx-loganalyze-es-loganalyze-application-loganalyze-api-log这四个 Skill 如果只由 AI Agent 开发者在语义相近的领域里描述向量距离会很近。用户说“帮我看看接口报错”模型可能命中analyze-api-log也可能命中analyze-application-log。一旦选错后续的执行路径直接跑偏。这里有个关键认知Skill 的选择本质上是分类问题不是越丰富越好。类别越多类与类之间的区分度就会被稀释。这和人类用工具箱是一样的——五把不同用途的刀放在桌面上闭眼都知道拿哪个五十把外观相似但用途略有差异的刀堆在一起你不看标签也会拿错。3.3 指令冲突与工作流割裂另一个被低估的问题是Skill 之间会互相打架。一个 Skill 里可能写着“所有数据库操作必须生成事务”另一个 Skill 里写着“为了性能批量更新不需要事务”。模型同时看到两条指导时会陷入左右互搏。它可能最终选择“事务优先”但代码风格明显变得犹豫甚至在注释里写满了自我否定。更麻烦的是多个 Skill 的存在会让 Agent 在工作流中途“切换状态”。比如用户要求“生成 Vue 组件并接入接口”。模型先通过“Vue 组件生成 Skill”搭好了组件框架然后切换到一个“接口对接 Skill”。这两个 Skill 如果对项目目录结构、命名规范、错误处理方式的约定不一致最终输出的代码就是割裂的前半段是风格 A后半段是风格 B。这种问题在单体 Prompt 时代反而少见因为所有约定在同一个提示词里有统一约束。拆成多个 Skill 后每个 Skill 是局部最优合在一起却可能不是全局最优。3.4 错误被封装得更深更难排查Skill 数量多了以后调试难度会成倍上升。当问题出现在单一 Prompt 中时你能直接看 Prompt 里哪里和模型输出冲突。当问题出现在多 Skill 场景时你需要先确定“模型选择哪个 Skill 了”然后看该 Skill 的执行逻辑再看它有没有正确被加载最后才能判断问题出在描述、加载还是脚本执行。这就像微服务原本写一个大型函数时可以快速定位错误拆成几十个微服务后一行日志定位不到根因需要链路追踪才能跨服务还原问题现场。很多 Agent 失败后不会告诉你“我选错了 Skill”它只会给你一个无明显逻辑的结果。你翻遍日志也找不到异常因为问题出在做选择的那个瞬间。4. 从工程视角看Skill 越多不是模型问题是架构治理问题如果只看“模型选错 Skill”你会觉得这是算法问题。但如果把视角拉高你会发现它本质上是架构治理问题。Skill 库之于 Agent就像微服务之于后端系统。微服务拆得好服务边界清晰业务迭代速度快拆得过度服务数量爆炸运维成本、链路复杂度、部署难度全线上涨最终把系统拖垮。Skill 是一样的。每个 Skill 就像一个小服务它的描述是 API 文档它的脚本是业务逻辑它被 Agent 调用的过程就是服务路由。当没有统一治理规范时每个人都会按自己的理解往库里面加 Skill最终造成职责重叠三个 Skill 都能做代码生成但细节不同描述随意有人写一句话有人写一大段歧义严重边界模糊没人能说清楚“该用哪个 Skill”的判定标准。到这一步Agent 的“变笨”就不是模型的问题而是库的腐化。所以治理 Skill 库的成熟度直接影响 Agent 是否能长期稳定产出。很多项目初期效果惊艳中期开始退化后期甚至被判定为“不可用”原因就在于没有治理完善的 Skill 库。5. 案例一个被 Skill 拖垮的 Agent 配置假设你在一个 AI 编程助手工具里配置了这样一组 Skillskills/ ├── code-review.md ├── code-generation.md ├── code-optimization.md ├── generate-api-client.md ├── generate-sql.md ├── analyze-logs.md ├── analyze-es-logs.md ├── frontend-development.md ├── vue-development.md ├── react-development.md ├── ui-design.md ├── math-modeling.md └── drawio-diagram.md这些 Skill 看起来都很丰富问题却很明显。先看code-review.md的内容--- name: code-review description: 审查代码质量、发现潜在问题、给出优化建议也可以用于代码理解、代码解释和代码重构。当用户需要评估代码或改进代码质量时使用。 ---再看code-optimization.md--- name: code-optimization description: 改进代码性能和可维护性也可以进行代码审查发现性能瓶颈。 ---这两个 Skill 的描述高度重叠。用户说“帮我看看这段代码有没有问题”模型会随机选择其中任意一个导致输出风格和检查标准不一致。用户说“优化一下这段代码”模型可能走code-review而不是code-optimization结果只是分析了一遍没有给出优化后的代码。再比如用户说“分析一下 ES 日志”系统里既有analyze-logs又有analyze-es-logs还有analyze-nginx-logs。每个 Skill 都只描述了“分析日志”没有明确触发边界。模型极可能选错。问题不在于单个 Skill 写错了而在于整体没有区分度。候选集合越密模型的选择决策越不稳定。如果重新设计一个更干净的结构可能是skills/ ├── generate-api-client-from-openapi.md ├── analyze-application-log.md ├── generate-rest-api-test-cases.md └── generate-vue-component-from-design.md每个 Skill 只干一件事描述里写明触发条件和不触发条件彼此之间尽量不重叠。这里特别想提醒Skill 描述里的“不触发条件”和触发条件一样重要。很多人只写“什么场景使用”不写“什么场景不要用”等于没给模型划定边界。看一个指向明确的示例--- name: generate-api-client-from-openapi description: 当用户提供 OpenAPI/Swagger 文档路径或 URL并要求生成 API 客户端代码时使用。如果输入中没有 openapi.yaml 或接口定义 URL不要触发。 ---这个描述明确了两件事触发条件有 OpenAPI 文档路径或 URL并要求生成客户端不触发条件没有接口定义文档。模型看到这种描述后决策边界会很清晰。6. Skill 与 MCP、插件边界别再搞混了现在很多开发者会把 Skill、MCP Tool、普通插件混为一谈导致设计出来的 Skill 既不像 Skill也不像 Tool。这里用一个表格把概念隔清楚维度SkillMCP Tool普通插件本质任务执行方案与知识外部系统调用通道软件功能扩展解决什么问题告诉 Agent 怎么做让 Agent 能做什么让宿主程序多什么能力是否需要模型选择需要模型决定是否加载需要模型决定是否调用通常无需模型选择典型例子代码审查规范、日志分析方法数据库查询接口、天气 APIIDE 插件、语法高亮更新方式修改 prompt 与资源文件部署服务端/注册工具安装扩展包从这个表格可以得出几个实用判断如果某个能力需要“告诉模型一套操作流程”用 Skill如果某个能力需要“连接外部系统实时交互”用 MCP Tool如果一个能力既不改变模型行为又不连接外部系统它就不该出现在 Agent 的 Skill 库或 Tool 列表里。很多人把“写一个 Skill 文件”当成给 Agent 增加能力的唯一方式这其实是一种偷懒。过度依赖 Skill会让 Agent 的能力边界变成一堆人工规则的堆叠失去模型自身的泛化能力。Skill 的价值是给模型提供“非它不可”的领域知识不是替代模型的默认能力。如果模型本身已经能做这件事你就没必要单独加一个 Skill 来增加选择负担。7. 构建一个干净 Skill 库工程方法与示例到这里思路应该清晰了我们不是不要 Skill而是要有设计、有约束、可治理的 Skill 库。下面是一套可以直接用起来的工程化方法。7.1 命名规范动词 对象 场景Skill 名称是模型选择时的第一信号。推荐采用“动词 对象 场景”的命名方式并且尽量做到“一望即知做什么”。推荐示例generate-api-client-from-openapianalyze-nginx-access-loggenerate-sql-from-requirementcreate-vue-component-from-design不推荐示例helpercode-toolsutilsjob如果名字含混不清意味着模型只能依赖 description 判断而 description 越长模糊度越高。7.2 描述规范写触发条件也写不触发条件这是最重要的实践。所有 Skill 的描述都应遵循一个模板--- name: 技能名称 description: 一句话说明这个 Skill 做什么。当且仅当满足以下条件时使用触发条件。如果出现以下情况不要使用不触发条件。 ---用一个前端场景的例子--- name: generate-vue-component-from-design description: 根据设计稿或需求描述生成 Vue 单文件组件。当用户提供设计稿截图、组件需求描述或需要创建 Vue 组件时使用。如果用户只是询问 Vue 基础知识不要使用。 ---加了一句“如果用户只是询问 Vue 基础知识不要使用”核心的排除逻辑就有了。这句话能显著降低模型选错 Skill 的概率。7.3 审计 Skill 库先看清现状要治理一个已经膨胀的 Skill 库第一步是盘点。下面这个 Python 脚本可以帮你快速列出所有 Skill 的元信息# 文件路径tools/list_skills.py from pathlib import Path import yaml skills_dir Path(skills) for skill_file in sorted(skills_dir.rglob(*.md)): try: content skill_file.read_text(encodingutf-8) front_matter content.split(---)[1] meta yaml.safe_load(front_matter) name meta.get(name, skill_file.stem) desc str(meta.get(description, )).replace(\n, ) print(f{name}: {desc[:100]}) except Exception as exc: print(f解析失败 {skill_file}: {exc})运行之后你会看到一个完整的清单。接下来人工审一遍把描述重叠的 Skill 挑出来合并把边界不清晰的补上触发条件把长期没被调用的 Skill 归档或删除。7.4 控制数量一个领域尽量只留一个 Skill不要在一个领域放三个相似的 Skill。比如“日志分析”领域你只需要一个analyze-application-log最多再按数据源拆成两个不要做 5 个。每增加一个同类 Skill模型的决策容错空间就缩小一圈。如果确实要按不同数据源拆分就必须在描述里写明“什么时候选我不选另一个”。在这个字段上多花时间比靠模型自己猜测要可靠得多。7.5 把大段示例移出描述区Skill 描述里不需要写完整代码示例也不需要写长流程。将它们放到 Skill 目录下的资源文件里只有在需要时才读取。模型的上下文应该留给“选择信号”和“核心指令”而不是一整片参考文档。一种推荐目录结构skills/ ├── analyze-application-log/ │ ├── SKILL.md │ ├── steps.md │ ├── examples/ │ │ └── sample-log-analysis.md │ └── scripts/ │ └── parse_log.pySKILL.md只写“何时用”和“核心思路”详细步骤放在steps.md脚本放在scripts目录。模型决定加载 Skill 后再有选择地读取资源文件。7.6 建立小型回归评测集Skill 库的每一次变更都可能影响 Agent 的整体表现所以需要一套“回归测试”机制。可以准备 10 到 20 条典型任务覆盖大家最常用的场景。每次新增、删除或修改 Skill 后都跑一遍这些任务对比输出质量。建立评测集后你会更容易发现“哪次修改把效果拉低了”。有一个很简单的做法把评测任务放到一个evals/cases.md文件里每次变更后批量提交给 Agent并记录输出质量评分。这个做法不需要专门的评测平台也可以发现明显退化。8. 常见问题与排查思路Skill 相关的问题往往很难一眼定位下面列一些高频问题与排查方向。问题现象可能原因排查方式解决方案Agent 明明有对应 Skill却不触发描述与用户意图匹配度不够查看 Agent 输出日志和候选 Skill 命中记录重写 description补充触发条件Agent 触发了错误 Skill相似 Skill 存在描述重叠对比候选 Skill 的描述文本明确边界合并或细化区分添加新 Skill 后原来能力明显变差上下文被 Skill 元数据挤占对比开启和关闭新 Skill 后的输出精简描述按需加载资源Agent 反复调用 Skill 但无结果Skill 脚本执行失败错误被吞掉检查脚本 stderr 和工作目录补充错误日志和失败回调响应速度明显变慢Skill 数量过多或检索链路太重分析调用耗时和 token 消耗缓存历史结果减少候选数量多个 Skill 输出风格不一致两个 Skill 约定冲突对比各自输出示例统一规范合并冲突 Skill排查第一原则先看 Agent 的“选择日志”。大多数 Agent 框架会记录模型决定调用 Skill 时的 reasoning 过程。哪怕只记录候选 Skill 和最终选择也能帮你快速判断问题是在“选错了”还是“执行错了”。如果选择日志不可用可以改用二分排查法把 Skill 库暂时裁剪到只剩目标场景相关的一两个 Skill看问题是否消失。如果消失问题基本就出在 Skill 间的选择和上下文干扰上。9. 最佳实践与工程建议最后把 Skill 库治理沉淀成一套可持续执行的最佳实践。9.1 先不加 Skill先跑通再按痛点补充新项目接入 Agent 时不要一上来就建 Skill 库。先让 Agent 用默认能力跑通核心任务记录它哪里做得不好再按痛点逐个添加 Skill。增量式添加比一次性建库更可靠。9.2 每次变更都做回归验证Skill 的增删改不是文档修改是行为变更。建议把“变更 回归评测”绑定成固定流程在 CI 或团队协作卡里体现。9.3 保持 Skill 库的“职责单一”每个 Skill 应该只有一个明确职责。如果一个 Skill 的 description 里出现了两种明显不同的任务就把它拆成两个并划清边界。9.4 定期清理长期未使用的 SkillSkill 也会过期。业务规则变了、框架升级了、模型能力变强了原本必要的 Skill 可能已不再需要。定期查看哪些 Skill 长期没有被选中该归档就归档。9.5 统一由一人或一个小组负责治理Agent 的 Skill 库如果谁都能改很快会退化。更建议指定一个“Skill 库负责人”审查命名、描述、边界并负责回归验证。9.6 关注 token 消耗变化Skill 元数据虽然看起来不大但在高频调用下会放大 token 成本。对比 Skill 库调整前后的 token 消耗能从经济角度反向验证“Skill 是否过度膨胀”。9.7 让描述像契约一样严格描述里每个词都可能影响模型决策。写 Skill 描述时要像写 API 文档那样严格少用模糊词汇多用明确条件和排除项。10. 结尾让你的 Skill 库瘦下来Skill 不是给 Agent 的奖励不是越多越好。真正有价值的 Skill 库应该是精简、边界清晰、可维护的。当你觉得 Agent 变笨时先别急着怀疑模型能力去检查你的 Skill 库是不是已经烂成一团浆糊。把相似描述合并把不触发条件补上把长期不用的技能归档效果往往立竿见影。一个干净利落的 Skill 库可能只需要三到五个真正管用的技能就能让 Agent 稳定产出高质量结果。与其贪多不如先让库里的每一个 Skill 都经得起检查。