在 AI Agent 开发群里经常能看到一个经典问题为什么我把常用的能力都封装成了 Skill数量越来越多Agent 反而越来越笨明明知识更全、工具更丰富结果它连最简单的任务都要绕路甚至频繁调用错误的技能。这个现象并不只出现在新手项目里很多已经上线的生产环境同样会踩到。本文会从 AI Agent 的 Skill 机制讲起分析“Skill 越多、效果越差”的根本原因再给出完整的优化思路和可落地的配置示例。如果你想搭建自己的 Agent或者正在维护一个不断膨胀的 skill 库这篇文章可以帮你理清“做减法”的具体方法。1. 先搞清楚AI Agent 的 Skill 到底是什么1.1 从概念说起AI Agent 是一个能够感知环境、做出决策并执行任务的智能系统。它不像普通聊天机器人那样只生成文本而是能够调用工具、读取文件、执行命令甚至完成一整套工作流。Skill 是 Agent 的能力单元。你可以把它理解成一本“操作手册”告诉 Agent 在什么场景下该做什么、按什么步骤做、有哪些边界和禁忌。一个 Skill 通常包含三部分内容组成部分作用示例描述信息告诉模型这个 Skill 是干什么的“用于分析 Nginx 错误日志”执行步骤拆解任务流程先读取日志再统计状态码最后输出报告资源引用提供脚本、提示词、配置文件Python 脚本、SQL 模板、Markdown 说明文档所以Skill 不是单纯一段 Prompt也不是一个函数库。它是一种“面向 Agent 的可复用能力封装”。1.2 Skill 与工具、插件、MCP 的区别这部分容易混淆我习惯用一个比喻理解工具Tool是“手”能执行具体动作比如搜索、发请求、执行命令。MCP 是“USB 接口标准”让不同 Agent 可以统一连接外部工具和数据源。Skill 是“说明书”告诉 Agent 什么时候该用这只手、怎么用好这只手。Skill 可以调用工具也可以调用 MCP 提供的资源。比如一个“日志分析 Skill”内部会定义什么时候调用日志查询工具如何解析返回的 JSON 数据最后怎样生成报告。工具和能力本身可能没有变化但 Skill 决定了 Agent 会不会正确使用它们。1.3 为什么越来越多的人开始用 Skill在没有 Skill 的年代Agent 的能力完全依赖模型临场发挥。你需要在 Prompt 里写清楚各种规则但规则一多上下文就乱。Skill 的价值有三个复用把一次成功的任务流沉淀下来下次直接加载。约束限制模型的自由发挥减少“创造性”错误。标准化团队内部可以共享同一套任务执行规范。很多开发者在尝试 Skill 后第一反应都是“越多越好”。看到新的技能就加进 skill 库这个思路看起来合理但实际效果往往相反。2. 为什么 Skill 越多Agent 反而越笨2.1 上下文窗口被无效信息撑满大语言模型的注意力机制决定了它只能处理有限的上下文。现代模型虽然上下文窗口越来越大但这并不意味着它可以无限地“同时使用”所有信息。假设一个 Skill 的描述加上执行步骤大约需要 800 个 token。如果挂载 20 个 Skill仅 Skill 本身的描述就要占用 16000 个 token。这些内容会排在系统提示词和对话历史之间占据大量有效空间。更关键的是当上下文变长之后模型对关键信息的注意力会被稀释。它需要从一堆不相关的 Skill 描述中找出“当前任务到底应该用哪一个”这个过程本身就容易出错。这不是模型“不够聪明”而是信息架构设计出了问题。2.2 路由与选择困难Agent 在实际运行时会先判断当前任务属于哪个 Skill 的职责范围这本质上是一个“意图路由”问题。候选 Skill 越多路由的准确率就越低。比如你同时挂载了“日志分析”和“异常诊断”两个 Skill它们都包含“读取日志、定位错误”的描述。模型可能随机选择其中一个或者把两者的步骤混在一起执行。我们曾经在一个测试场景中放了 3 个高度相关的 Skillparse_nginx_log解析 Nginx 日志并统计状态码analyze_error_log分析应用错误日志并定位异常response_time_report统计接口响应时间并生成报告结果 Agent 在只要求“统计 404 数量”的任务中竟然先调用了analyze_error_log绕了一大圈才回到正确逻辑。这是因为候选描述太相似模型的注意力被分散了。2.3 Skill 之间的指令冲突与边界重叠当 Skill 数量增加不同 Skill 之间还可能存在互相矛盾的指令。举一个真实案例一个frontend-guideSkill 要求“所有 UI 修改必须符合企业设计规范”。一个quick-prototypeSkill 要求“优先输出可运行的 HTML 原型样式可以简化”。如果两个 Skill 同时挂载Agent 就不知道应该遵守哪个规范。它可能每次都会输出一段“我注意到存在冲突”的话甚至来回切换规则导致任务无法完成。这类冲突很难通过简单堆更多 Skill 解决因为每一种新 Skill 都是一条新的“规则”规则之间的矛盾会随着数量指数上升。2.4 工具调用噪声和错误率上升Agent 在执行任务时并不是“用一次工具就结束”它可能会反复尝试。如果 Skill 库里有大量工具调用步骤模型在选择工具时会出现更多噪声。比如它可能先调用了一个无关的搜索工具再调用一个只读脚本最后才执行真正的处理逻辑。这个过程不仅浪费 token还可能因为错误工具返回了不完整或错误的数据导致后续判断全部出错。工具调用链越长失败概率越高。这个规律在传统软件工程里也成立在 Agent 中更加明显。我们可以用一个表格总结“Skill 少”和“Skill 多”的差异对比维度Skill 少而精Skill 多而杂上下文占用低模型聚焦强高注意力被稀释意图路由准确率高容易选错指令一致性容易维护容易冲突工具调用链路短而稳定长且容易中断调试成本低高2.5 维护成本高旧 Skill 成为“知识污染源”很多人忽略了一点Skill 不是一次性资源它需要持续维护。如果脚本依赖的 API 版本变了或者内部域名变了旧的 Skill 就会失效。失效的 Skill 如果还在 skill 库里就相当于向模型投放了过期“情报”。模型会把它当成有效知识实际上它已经不能正常执行。更麻烦的是团队里不同成员可能会各自添加 Skill没人负责整体审查。久而久之Skill 库变成一个没有人完全了解的“黑盒”Agent 的表现自然越来越不可控。3. 设计原则从“堆数量”到“做减法”既然 Skill 太多会拖累 Agent那应该如何设计一套合理的 Skill 体系下面三条原则非常关键。3.1 单一职责一个 Skill 只做一件事写 Skill 时不要追求“大而全”。一个 Skill 只解决一个明确的问题描述应该精准避免出现多个可能性。正确示例描述该 Skill 用于解析 Nginx access.log并按状态码统计请求数量。若日志格式不是 Nginx 默认格式请停止执行并提示用户。错误示例描述该 Skill 用于日志分析、错误排查、性能统计、报告生成偶尔也可以做数据清洗。第二种描述看起来能力很强但模型无法判断“当前场景应该启用哪一部分逻辑”。边界越模糊路由错误越严重。3.2 控制粒度区分基础能力与组合能力很多 Skill 其实是在重复调用更底层的能力。比如“生成周报”和“生成日报”可以共享同一个数据查询逻辑。在体系设计上可以把底层能力拆成基础 Skill再把面向场景的流程做成组合 Skill。组合 Skill 内部引用基础 Skill而不是复制粘贴整套逻辑。但这不代表基础 Skill 要无限拆分。一个合理的参考标准是如果模型在绝大多数任务中都只需要一个 Skill那这个 Skill 就是基础能力如果它只有在特定场景下才使用那它应该是一个专项 Skill。3.3 分级加载不要让所有 Skill 常驻现代 Agent 框架大多支持按需加载。我们完全可以做到默认只挂载 3 到 5 个核心 Skill。遇到特定任务时通过关键词或目录约定动态加载对应的 Skill。禁止无关 Skill 进入当前会话上下文。这种“分级加载”策略比把所有 Skill 全部塞给模型要高效得多。它既保留了 Skill 的复用能力又避免了上下文膨胀。3.4 给新增 Skill 设置三道检查门每次想往 skill 库里加一个新 Skill 之前先回答三个问题这个 Skill 是否会被重复使用如果只是临时任务那不应该做成 Skill。如果不挂载这个 SkillAgent 真的处理不了吗有时候模型本身已经具备能力额外 Skill 反而是干扰。这个 Skill 能不能被已有 Skill 组合覆盖能覆盖就不新增。这三个问题听起来简单实际执行时很有效。大部分无效 Skill 在第三道门前就会被拦住。4. 环境准备与版本说明在进入实战之前先说明本次示例使用的环境。由于 AI Agent 生态变化非常快不同工具对 Skill 的目录结构和加载方式并不完全一致。本文以“文件目录型 Skill 系统”作为示例这也是 Claude Code、Codex 等工具中常见的一种实现方式。你不需要强求版本完全一致重点理解设计思路再迁移到自己的工具链中。示例环境操作系统Linux / macOS / WindowsWSL运行环境Python 3.10 以上Agent 工具任选支持 Skill 文件目录的工具例如 Claude Code、Codex 或自己实现的 Agent 框架配置文件格式JSON、Markdown下面所有代码都只是示例请根据你实际使用的 Agent 工具调整路径和字段名。5. 实战如何构建一份“小而精”的 Skill 系统5.1 设计一个最小目录结构我们先从目录结构说起。一份合理的 Skill 系统应该让 Agent 一眼就能看出有哪些能力并且每个能力之间互不干扰。agent-skills/ review/ SKILL.md scripts/ run_review.py log-analysis/ SKILL.md prompts/ summary_template.md config/ agent.config.json目录说明agent-skills/是 skill 库根目录。review/和log-analysis/是两个 Skill。每个 Skill 都有独立的SKILL.md作为主描述文件。脚本和模板放在 Skill 自己的子目录中隔离得越干净越不容易互相污染。5.2 编写一份克制的 SKILL.mdSKILL.md是 Agent 看到的核心文件。一份好的 SKILL.md 不应该长篇大论而要聚焦在“触发条件、执行步骤、边界约束”三个部分。下面是一个代码审查 Skill 的示例--- name: code-review description: 对指定目录下的代码进行静态审查生成问题列表和改进建议。 when_to_use: 当用户要求检查代码质量、寻找潜在 Bug 或提交代码审查结果时使用。 version: 1.0.0 --- # Code Review Skill ## 输入 - target_dir: 需要审查的代码目录路径 ## 执行步骤 1. 读取 target_dir 下的所有源代码文件排除 node_modules、venv 等依赖目录。 2. 使用 scripts/run_review.py 扫描代码中的常见问题包括未捕获异常、资源未释放、硬编码密钥。 3. 根据扫描结果生成 Markdown 报告输出到 target_dir/review_report.md。 ## 约束 - 不要修改任何源代码文件。 - 如果 target_dir 不存在直接报告错误不要尝试自动创建目录。 - 只关注代码质量不执行业务逻辑变更。 ## 示例 用户输入请审查 ./src 目录下的代码 输出生成 ./src/review_report.md并列出 ERROR 和 WARNING 数量。这个文件的核心就在于“克制”。它没有堆砌各种代码规范而是把模型最需要的信息浓缩出来。5.3 配置按需加载接下来看配置文件。很多 Agent 工具都支持在会话级别指定需要加载哪些 Skill。这里给出一个简化的 JSON 示例{ default_skills: [code-review], available_skills: { code-review: { path: agent-skills/review, enabled: true, triggers: [code review, 代码审查, 检查代码] }, log-analysis: { path: agent-skills/log-analysis, enabled: false, triggers: [日志分析, parse log, analyze log] } }, max_loaded_skills: 3 }配置说明default_skills每个会话默认加载的 Skill建议不超过 3 个。available_skills所有可用的 Skill但enabled字段控制是否常驻。triggers当用户输入命中关键词时可以动态加载对应 Skill。max_loaded_skills限制最多同时加载的 Skill 数量从机制上防止膨胀。把log-analysis的enabled设为false意味着它不会一直占上下文。只有用户明确提到日志相关关键词时Agent 才会临时加载它。5.4 运行与验证可以写一个小脚本验证 Skill 加载效果。这里以 Python 为例展示如何读取配置只输出当前启用的 Skillimport json with open(agent-skills/config/agent.config.json, r, encodingutf-8) as f: config json.load(f) loaded_skills [ name for name, skill in config[available_skills].items() if skill.get(enabled) or name in config[default_skills] ] print(当前加载的 Skill:, loaded_skills) print(总 Skill 数:, len(config[available_skills])) print(加载比例: {:.0%}.format(len(loaded_skills) / len(config[available_skills])))预期输出当前加载的 Skill: [code-review] 总 Skill 数: 2 加载比例: 50%说明当前上下文只需要加载一个 Skill另一个被推迟到需要时再启用。这种方式能明显减少 Agent 的“选择负担”。6. 如何诊断你的 Agent 是不是被 Skill 拖累了如果你已经发现 Agent 效果变差但不确定是不是 Skill 引起的可以按下面的方法做一轮诊断。6.1 观察三类异常现象第一类调用无关 Skill。比如用户要求“统计日志里的错误数量”Agent 却先调用了“UI 规范生成”工具。第二类任务变慢且 token 消耗暴涨。同一任务在 Skill 少时只需要 5000 token挂载 15 个 Skill 后消耗变成 15000 token。第三类同一任务反复修改结果。Agent 刚开始按 A Skill 执行执行到一半又跳到 B Skill 的逻辑最后返回一个混合答案。如果出现以上任意一种都需要考虑 Skill 管理是否存在问题。6.2 用最小化复现定位问题不要直接删掉大量 Skill而是先用“最小化复现”的方式定位问题。步骤很简单先禁用全部 Skill只保留系统 Prompt跑一次任务作为基线。逐个启用 Skill每次只增加一个观察结果是否变差。当发现某个 Skill 加入后效果明显下降暂停并检查该 Skill 的职责边界。在命令行中你可以用临时配置文件来完成这个操作cp agent-skills/config/agent.config.json /tmp/agent.config.json.bak # 临时禁用某个 skill jq del(.available_skills[log-analysis]) /tmp/agent.config.json.bak agent-skills/config/agent.config.json # 运行测试任务后恢复 cp /tmp/agent.config.json.bak agent-skills/config/agent.config.jsonjq是常用的 JSON 处理工具如果你的环境没有安装也可以手动编辑配置文件。重点是修改配置后一定要恢复避免影响其他人的使用。6.3 建立回归测试清单Skill 优化不是一次性的建议准备 3 到 5 个固定测试任务作为回归测试基线。测试任务期望结果最大允许耗时最大 token 数审查代码并输出报告生成报告文件不修改源码2 分钟8000分析 Nginx 日志输出状态码统计表1 分钟5000生成接口摘要输出 Markdown 文档1 分钟4000每次调整 Skill 配置后都跑一遍这组测试。如果某一项指标明显恶化说明这次调整大概率引入了问题。7. 常见问题与排查思路下面整理几个最常见的 Skill 管理问题供大家快速对照。问题现象常见原因解决思路Agent 完全忽略新加的 SkillSkill 描述不包含触发条件或描述与其他 Skill 重叠完善when_to_use和triggers确认加载逻辑多个 Skill 互相冲突职责边界不清指令矛盾按“单一职责”原则拆分或合并删除冲突内容上下文被撑爆任务变慢所有 Skill 常驻加载使用按需加载设置max_loaded_skills工具调用总是选错Skill 描述太相似增加区分度比如明确“不适用于某种日志”旧 Skill 失效但 Agent 还在用维护缺失过期知识残留添加版本号定期清理未使用 Skill排查顺序建议是先看加载列表再看上下文大小最后看 Skill 内容本身。举个例子如果 Agent 没有调用新 Skill你可以先确认配置文件里的enabled是否为true再看triggers是否覆盖了用户输入的说法。很多时候并不是模型不听话而是配置条件没匹配上。8. 最佳实践与工程建议8.1 命名规范Skill 的命名建议采用“动词 对象”的格式比如review-codeparse-loggenerate-report避免使用“utils”“misc”“toolbox”这类无法表达功能的通用名称。命名清晰路由准确率会明显提升。8.2 版本管理与变更记录Skill 是代码资产应该用 Git 管理。在 SKILL.md 的 frontmatter 中加上版本号并在变更时记录 changelog--- name: review-code description: ... version: 1.2.0 changelog: - 1.2.0: 增加对 Python 类型标注的检查 - 1.1.0: 修复误报问题 ---这样当 Agent 表现异常时你可以快速回滚到上一个稳定版本。8.3 Skill 和 MCP 如何选择很多开发者会问有了 MCP还需要写 Skill 吗我的理解是MCP 解决的是“连接什么”的问题Skill 解决的是“怎么用好连接”的问题。如果外部系统是一个数据库你可以用 MCP 暴露查询接口但 Agent 不一定知道要先用哪个接口、如何判断返回结果是否正常。这时需要 Skill 来封装调用流程。反过来如果某个能力只需要一个简单的 API 调用不需要复杂步骤那直接用 MCP 工具即可不需要额外写 Skill。两者的边界不应该是“替代”关系而是“分工”关系。8.4 安全边界与最小权限Skill 里的脚本和命令应该遵循最小权限原则。不要在 Skill 中内置带敏感信息的连接串也不要允许 Agent 在生产环境执行高危操作。更安全的做法是Skill 只读取白名单目录。涉及数据库操作时统一通过只读账号。需要写入生产环境时必须显式二次确认。这一点在团队协作中尤其重要。Skill 一旦共享影响范围就会扩大。8.5 团队协作与新增 Skill 评审建议在团队中建立一个轻量评审机制新增 Skill 必须经过“设计三问”并且由至少一名熟悉 Agent 机制的同学确认职责边界不重叠。Skill 库和代码库一样是有生命周期的。好的 Skill 库应该保持“少而精”而不是逐渐膨胀成一个“大杂烩”。9. 总结与下一步回到开篇的问题为什么 Skill 越多Agent 反而越笨因为 Skill 不只是知识它还是上下文、路由约束和行为规范。每一份 Skill 都会占用模型的注意力而注意力是有限资源。与其追求数量不如控制质量让 Agent 在真正需要的时刻只看到最合适的一份说明。下一步你可以先做三件事盘点当前 skill 库删除 30 天内从未被调用的 Skill。给所有常驻 Skill 的 SKILL.md 加上when_to_use和constraints。建立一套 3 个任务的回归测试用数据判断 Skill 优化是否有效。Skill 不是收藏夹而是工具库。少一点准一点你的 Agent 才能真的变聪明。如果你也遇到过类似的“Skill 越多越笨”的情况不妨按照这篇文章的思路做一轮减法再对比一下效果。