1. 装了十几个 Skill 为什么还是不好用我自己踩过这个坑。去年下半年开始我陆续给自己的 Agent 环境装了十几个 Skill从代码审查、文档生成、测试用例编写到会议纪要整理几乎把能想到的场景都覆盖了一遍。结果呢真正高频使用的只有两三个剩下的要么触发不了要么触发了但输出质量还不如我直接写提示词。当时我的第一反应是Skill 质量不行于是又去搜罗新的 Skill装完还是老样子。后来我花了一个周末把每个 Skill 的SKILL.md从头到尾读了一遍又对照自己实际的使用记录做了复盘才发现问题根本不在 Skill 本身而在于我从来没认真想过一件事我的 Agent 到底缺什么能力。我装 Skill 的逻辑是这个功能看起来有用而不是我的工作流里有一个明确的缺口这个 Skill 刚好能补上。这两者的差别就像你家里已经有三把螺丝刀了看到第四把还是买但真正缺的其实是一把扳手。这篇文章想聊的就是这个事。Skill、AI Agent、SKILL.md、上下文窗口这些概念现在满天飞但大部分人装 Skill 的方式是错的。我会从能力缺口这个角度出发讲清楚怎么判断你的 Agent 真正缺什么、怎么用 SKILL.md 把缺口补上、怎么避免上下文窗口被无效 Skill 挤爆。不管你是刚接触 Agent 的新手还是已经装了一堆 Skill 但效果不理想的老手应该都能从里面找到对自己有用的东西。2. 先搞清楚 Skill 到底解决了什么问题2.1 Skill 不是插件是能力的封装很多人把 Skill 理解成给 AI 装插件这个类比不太准确。插件通常是扩展功能边界比如浏览器装个插件就能截图。Skill 更像是给 Agent 一套做事的方法论和操作手册它不改变模型本身的能力上限但能显著改变模型在特定任务上的表现下限。举个例子。你让一个没有 Skill 的 Agent 帮你做代码审查它可能会给你一些泛泛的建议比如建议增加错误处理注意边界条件。但如果你装了一个专门做代码审查的 Skill它的SKILL.md里可能定义了审查清单、严重程度分级标准、输出格式模板甚至包含了常见反模式的检查规则。这时候 Agent 的输出就会从泛泛而谈变成逐条对照、有据可依。所以 Skill 的核心价值不是让 AI 能做它本来不能做的事而是让 AI 在做某件事的时候按照你期望的标准和流程来做。理解这一点很关键因为它直接决定了你判断该不该装这个 Skill的标准。2.2 SKILL.md 里到底装了什么一个典型的SKILL.md通常包含几个部分触发条件、能力描述、操作步骤、输出格式、边界说明。触发条件决定了 Agent 在什么情况下会调用这个 Skill能力描述告诉 Agent 这个 Skill 能做什么操作步骤是具体的执行流程输出格式规定了结果长什么样边界说明则划定了这个 Skill 不负责什么。我见过很多人写SKILL.md的时候只写能力描述不写触发条件和边界说明。结果就是 Agent 要么在不该用的时候用了要么在该用的时候没触发。这两个问题都会让 Skill 的实际可用性大打折扣。提示写SKILL.md的时候触发条件和边界说明的重要性不亚于能力描述本身。一个没有明确边界的 Skill就像一个没有说明书的工具用起来全靠猜。2.3 上下文窗口是稀缺资源这是很多人忽略的一个点。每个 Skill 的SKILL.md都要占用上下文窗口的空间。你装了十几个 Skill如果每个SKILL.md平均 2000 字那就是两万多字的基础占用。再加上系统提示词、对话历史、当前任务的相关文件上下文窗口很快就会被填满。上下文窗口被填满的后果是什么Agent 会开始遗忘早期信息或者对当前任务的注意力被稀释。表现出来就是明明装了某个 Skill但 Agent 好像忘了它的存在或者输出质量突然下降因为模型要在大量信息中分配注意力。所以装 Skill 不是越多越好。每装一个 Skill你都要问自己这个 Skill 占用的上下文空间值不值得它带来的能力提升能不能覆盖它造成的注意力稀释3. 诊断你的 Agent 到底缺什么能力3.1 从失败案例反推缺口判断 Agent 缺什么能力最直接的方法不是看它能做什么而是看它在哪些任务上反复做不好。我自己的做法是建一个简单的记录表每次 Agent 输出不理想的时候记下来三件事任务是什么、输出哪里不对、我期望的输出是什么样。积累一两周之后你会发现失败案例会呈现出明显的聚类。比如你可能发现Agent 在需要结构化输出的任务上反复出问题或者在需要遵循特定规范的任务上总是跑偏又或者在需要多步骤推理的任务上容易跳步。这些聚类就是你的能力缺口。我整理过一份自己的失败案例聚类表大概长这样失败类型典型表现出现频率对应缺口输出格式不稳定有时用列表有时用段落字段缺失高缺少输出格式约束规范遵循不到位知道规范但执行时遗漏中缺少检查清单多步骤任务跳步中间步骤被省略中缺少流程拆解领域知识不足专业术语用错低缺少领域知识注入这张表比任何Skill 推荐清单都有用因为它是从你自己的实际痛点出发的。3.2 区分模型能力不足和流程缺失不是所有问题都能靠 Skill 解决。有些问题是模型本身的能力边界比如让一个文本模型去做精确的数学计算装再多 Skill 也没用。有些问题则是流程缺失比如模型有能力做代码审查但不知道你的审查标准是什么这时候一个 Skill 就能解决。怎么区分我的判断方法是如果这个问题换一个更详细的提示词就能解决那大概率是流程缺失适合用 Skill 来固化如果换更详细的提示词还是解决不了那可能是模型能力边界需要考虑换模型或者换工具。这个判断很重要因为很多人把模型能力边界的问题误判为流程缺失结果装了一堆 Skill 还是解决不了然后陷入是不是 Skill 不够好的循环。3.3 能力缺口的三个层次我把能力缺口分成三个层次对应不同的解决策略。第一个层次是格式缺口。Agent 有能力完成任务但输出格式不符合你的要求。比如你需要 JSON 但它给你 Markdown你需要表格但它给你段落。这类缺口最容易补一个简单的格式约束 Skill 就能解决。第二个层次是流程缺口。Agent 知道要做什么但不知道按什么步骤做。比如代码审查它知道要审查但不知道先看什么后看什么哪些是必须检查的哪些是可选的。这类缺口需要一个包含操作步骤和检查清单的 Skill。第三个层次是判断缺口。Agent 在需要做判断的地方判断不准比如严重程度分级、优先级排序、方案取舍。这类缺口最难补因为判断标准往往依赖领域经验和上下文。一个 Skill 能提供判断框架但最终效果还是取决于框架的质量和模型的执行能力。4. 用 SKILL.md 精准补上能力缺口4.1 触发条件要写得足够具体触发条件是SKILL.md里最容易被写坏的部分。我见过太多 Skill 的触发条件写成当用户需要代码审查时这种写法的问题在于需要代码审查这个判断本身就需要理解Agent 很容易误判。好的触发条件应该是具体、可观察的。比如不要写当用户需要代码审查时而是写当用户提供了代码片段并询问代码质量、潜在问题、改进建议时。后者描述的是可观察的行为特征Agent 更容易准确触发。我自己的经验是触发条件里最好包含三类信息用户的行为特征比如提供了代码片段、用户的意图特征比如询问代码质量、任务的输出特征比如期望得到改进建议。三类信息交叉验证触发准确率会高很多。4.2 操作步骤要拆到可执行粒度操作步骤是 Skill 的核心。很多人写操作步骤的时候喜欢写分析代码质量给出改进建议这种写法等于没写因为 Agent 本来就会这么做。操作步骤的价值在于把怎么做拆解到可执行的粒度。以代码审查 Skill 为例好的操作步骤应该是这样的先通读代码识别代码的整体结构和主要功能检查错误处理是否有未捕获的异常、是否有边界条件遗漏检查资源管理是否有未释放的资源、是否有内存泄漏风险检查并发安全是否有竞态条件、是否有死锁风险检查可读性命名是否清晰、注释是否充分、函数是否过长按严重程度分级输出严重问题、一般问题、建议改进每一步都是可执行的Agent 不需要自己判断该检查什么只需要按步骤执行。这就是 Skill 的价值所在。4.3 输出格式要给出模板输出格式这部分我的建议是直接给模板不要只给描述。比如不要写输出应该包含问题描述、严重程度、改进建议而是直接给一个 Markdown 模板## 审查结果 ### 严重问题 - **位置**文件:行号 - **问题**具体描述 - **建议**改进方案 ### 一般问题 ... ### 建议改进 ...给模板的好处是输出稳定性会大幅提升。Agent 不需要自己设计格式只需要填充内容。这对于需要批量处理或者需要后续程序解析的场景特别重要。4.4 边界说明要明确写出不做什么边界说明是最容易被忽略的部分但它其实很重要。一个 Skill 如果边界不清Agent 可能会在超出范围的任务上也调用它导致输出质量下降。边界说明应该明确写出这个 Skill 不负责什么。比如代码审查 Skill 的边界说明可以写本 Skill 不负责代码的自动修复只负责识别问题和给出建议不负责性能测试只负责静态代码分析不负责架构设计评审只负责代码层面的审查。写清楚边界之后Agent 在遇到超出边界的任务时就不会强行调用这个 Skill而是会寻找其他更合适的处理方式。5. 上下文窗口的分配策略5.1 算清楚你的上下文预算上下文窗口是有限的你需要知道自己的预算有多少。假设你的模型上下文窗口是 128K token系统提示词占了 2K对话历史平均占 10K当前任务相关文件占 20K那么留给 Skill 的空间大概是 96K。如果每个 Skill 的SKILL.md平均 2K token理论上你可以装 48 个 Skill。但理论值不等于实际值。因为 Skill 不是静态占用的Agent 在推理过程中还会产生中间结果这些也会占用上下文。而且上下文窗口被填得越满模型的注意力分配就越分散输出质量就越容易下降。我的经验值是Skill 占用的上下文不要超过总窗口的 30%。按 128K 算就是不要超过 38K。如果每个 Skill 平均 2K那就是最多装 19 个。但实际使用中我建议控制在 10 个以内留出足够的空间给对话和任务本身。5.2 分层加载而不是全量加载如果你的 Agent 框架支持动态加载 Skill那最好的策略是分层加载。把 Skill 分成常驻层和按需层。常驻层放那些几乎每次对话都会用到的 Skill比如输出格式约束、通用检查清单。按需层放那些只在特定任务中使用的 Skill比如代码审查、文档生成。按需层的 Skill 只在触发条件满足时才加载这样就能大幅节省上下文空间。我自己的配置是常驻层放 3 个 Skill按需层放 10 个左右实际使用中上下文占用一直很健康。5.3 定期清理低效 Skill装了 Skill 之后不是就完事了需要定期复盘。我的做法是每个月看一次 Skill 的使用记录把过去一个月触发次数少于 3 次的 Skill 标记为待观察连续两个月触发次数少于 3 次的直接移除。这个标准看起来有点激进但实际执行下来你会发现真正高频使用的 Skill 就那么几个。那些低频 Skill 要么是触发条件写得不好导致触发不了要么是场景太窄实际用不上。不管是哪种情况留着它们都是在浪费上下文空间。注意移除 Skill 之前先确认它不是因为触发条件写得不好才低频。如果是触发条件的问题修触发条件比移除 Skill 更划算。6. 实操从零搭建一个能力缺口驱动的 Skill 体系6.1 第一步建立失败案例记录找一个你常用的笔记工具建一个表格字段包括日期、任务描述、Agent 输出、期望输出、失败类型。每次 Agent 输出不理想的时候就记一条。不用记太多细节但要把哪里不对和应该是什么样记清楚。这个记录不需要很正式我自己用的是最简单的 Markdown 表格记了大概两周就积累了三四十条。然后我把这些案例按失败类型分组发现主要集中在输出格式不稳定和规范遵循不到位这两类上。6.2 第二步聚类分析找缺口把失败案例按类型分组之后统计每类的出现频率。频率最高的那一类就是你的首要缺口。不要试图一次解决所有缺口先解决最高频的那个。我当时的统计结果是输出格式不稳定出现了 15 次规范遵循不到位出现了 12 次多步骤任务跳步出现了 8 次领域知识不足出现了 5 次。所以我优先解决的是输出格式问题。6.3 第三步为每个缺口写一个 Skill针对输出格式不稳定这个缺口我写了一个结构化输出Skill。它的触发条件是当任务需要结构化输出时操作步骤是识别任务需要的输出结构选择合适的模板按模板填充内容检查字段完整性输出格式部分给了几种常用模板列表、表格、JSON、Markdown 标题层级边界说明是不负责内容质量只负责格式规范。这个 Skill 写完之后输出格式不稳定的问题基本消失了。然后我按同样的方法处理了规范遵循不到位的问题写了一个检查清单Skill。6.4 第四步测试和迭代Skill 写完不是就完事了需要测试。我的测试方法是找十个之前失败过的案例用新 Skill 重新跑一遍看输出是否达到期望。如果十个里面有八个达到期望那这个 Skill 就算合格。如果低于八个就需要回去改SKILL.md。改的时候优先改触发条件和操作步骤这两个部分对效果的影响最大。输出格式和边界说明可以后面再调。6.5 第五步定期复盘和清理前面说过每个月复盘一次。除了清理低频 Skill还要看高频 Skill 有没有优化空间。比如某个 Skill 触发很频繁但输出质量一般那可能是操作步骤需要细化或者输出格式需要调整。我自己的复盘周期是一个月一次每次大概花半小时。这个投入是值得的因为 Skill 体系的质量直接决定了 Agent 的日常使用体验。7. 常见问题与排查技巧7.1 Skill 不触发怎么办Skill 不触发是最常见的问题。排查顺序是先看触发条件是不是写得太抽象如果是就改具体再看是不是有多个 Skill 的触发条件重叠导致 Agent 不知道该用哪个最后看是不是上下文窗口太满Agent 根本没看到这个 Skill。我遇到过最隐蔽的一种情况是两个 Skill 的触发条件高度重叠Agent 每次都在两个之间犹豫结果两个都没触发好。解决办法是明确划分两个 Skill 的边界或者在触发条件里加上优先级标记。7.2 Skill 触发了但输出质量差怎么办先看操作步骤是不是太笼统。如果操作步骤写的是分析并给出建议那输出质量差是正常的因为 Agent 没有明确的执行路径。把操作步骤拆细拆到每一步都是可执行的动作输出质量通常会有明显提升。如果操作步骤已经很细了但质量还是差那可能是输出格式没有约束好。给一个具体的模板让 Agent 按模板填充通常能解决大部分格式问题。7.3 上下文窗口不够用怎么办三个策略减少常驻 Skill 数量、启用按需加载、压缩SKILL.md篇幅。压缩篇幅的时候优先删掉那些正确的废话比如要仔细分析要认真检查这类没有操作指导意义的句子。保留触发条件、操作步骤、输出格式、边界说明这四类核心信息。7.4 多个 Skill 冲突怎么办Skill 冲突通常表现为 Agent 在多个 Skill 之间反复横跳或者输出里混杂了多个 Skill 的格式。解决办法是明确每个 Skill 的适用场景在触发条件里写清楚当 X 条件满足且 Y 条件不满足时使用。如果两个 Skill 确实有重叠考虑合并成一个或者拆成主 Skill 和子 Skill。问题类型排查顺序常见原因解决方向不触发触发条件→重叠检查→上下文条件太抽象、条件重叠、窗口满改具体、划边界、减常驻质量差操作步骤→输出格式→边界步骤笼统、格式无约束、边界不清拆细步骤、给模板、写边界窗口不够常驻数量→加载策略→篇幅常驻太多、全量加载、篇幅冗余减常驻、按需加载、压缩冲突适用场景→触发条件→合并场景重叠、条件模糊划边界、加优先级、合并8. 几个我踩过的坑和总结的经验第一个坑是贪多。刚开始的时候我觉得 Skill 越多越好装了十几个结果上下文窗口被占满Agent 反而变笨了。后来砍到 6 个效果反而更好。Skill 的价值不在于数量在于精准。第二个坑是触发条件写得太宽。我写过一个文档处理Skill触发条件写的是当用户需要处理文档时。结果 Agent 在几乎所有涉及文字的任务上都触发这个 Skill包括代码注释、聊天回复这些根本不需要文档处理的场景。后来把触发条件改成当用户提供文档文件并需要提取、转换、总结文档内容时触发就准确多了。第三个坑是忽略边界说明。我早期写的 Skill 基本不写边界说明结果 Agent 经常在超出范围的任务上调用 Skill输出质量很差。后来每个 Skill 都加上边界说明明确写出不做什么情况就好多了。第四个坑是不记录失败案例。我一开始是凭感觉判断 Agent 哪里做得不好结果改来改去都是改在表面。后来开始系统记录失败案例才发现真正的问题集中在两三个点上集中解决这几个点比到处打补丁有效得多。第五个坑是写完不测试。Skill 写完直接就用用了几天发现效果不好又回去改。后来改成写完先跑十个测试案例达标了再用省了很多来回折腾的时间。9. 关于 Skill 体系的一点个人体会我现在维持着一个 6 个常驻 Skill 加 8 个按需 Skill 的体系覆盖了我日常 90% 以上的使用场景。这个体系不是一次搭好的是经过三四轮迭代慢慢磨出来的。每一轮迭代都是从一个具体的失败案例出发找到缺口补上 Skill测试然后进入下一轮。如果你刚开始搭 Skill 体系我的建议是不要急着装一堆现成的 Skill。先花一周时间记录自己的失败案例找到最高频的两三个缺口针对性地写两三个 Skill。用一段时间再复盘再补。这样搭出来的体系是长在你自己的需求上的比任何推荐清单都管用。Skill 这个东西本质上是你把自己的工作方法和标准固化下来让 Agent 按照你的方式来做事。所以最重要的不是 Skill 本身写得多漂亮而是你有没有想清楚自己到底要什么。想清楚了Skill 就是水到渠成的事。