AI Agent Skill不生效？四步排查法让Skill真正被调用

把 Skill 文件写得漂漂亮亮，结果运行起来 AI 直接把你精心设计的流程丢到一边，或者干脆像没看见这个技能一样？这事儿我太有发言权了。过去大半年，我前前后后调过几十个 Skill，光是排查“为什么不听话”就占了将近一半时间。如果你也遇到过“Skill 文件明明放进去了、格式也没报错、AI 就是不按预想执行”的情况，先别急着怀疑模型，大概率问题就出在你写的那几段配置里。

这里先对齐一个大家最容易误解的词：Skill。在 AI Agent 生态里，Skill 本质上不是一串可执行代码，而是一份“给模型看的说明书 + 给模型用的参数模板”。它告诉模型三件事：什么时候该想起我、想起之后怎么干活、干活需要哪些输入。听起来简单，但偏偏就是这三点，每一点都能让 AI 整出幺蛾子。我把排查经验收敛成了四件事：先看触发描述能不能让 AI 认出来，再看指令正文够不够清晰，接着查参数定义跟真实需求对不对得上，最后确认 Skill 到底有没有被真正调用。这篇文章就把这四件事一层层拆开讲，并且用一个“会议纪要整理 Skill”的案例完整演示排查过程。不管你是第一次写 Skill，还是被生产环境里的 Agent 逼到快崩溃，这套思路都能直接套用。

1. Skill 没生效？先搞明白 AI 是怎么“看”Skill 的

1.1 Skill 的本质：一份给 AI 看的任务卡，不是程序源码

很多人在写 Skill 的时候，犯的第一个错就是把它当成“程序源码”。有人把逻辑写成堪比 Python 脚本的层层嵌套，恨不得让 AI 一行一行机械执行。实际上，Skill 更接近你递给临时工的一张任务卡：它需要在短时间内让 AI 明白“什么情况下接手、主要负责做什么、有什么边界限制”，而不是事无巨细的命令清单。

这个区分很重要，因为后面的所有排查思路都建立在它上面。如果你把 Skill 当代码，你会觉得“我已经写得很清楚了”，继而认为问题出在模型太笨；但如果你把 Skill 当任务卡，你就会开始琢磨：这张任务卡上的文字是不是让临时工产生了误解？有没有可能他根本没看见这张卡片？角度一转，排查方向就对了。

1.2 从触发到执行，一道 Skill 要闯四道关卡

一次“按预期执行”的 Skill 调用，并不是“模型看到 Skill 然后照做”这么简单。它背后其实要连续闯过四道关卡：

第一关是触发识别。模型在看到用户提问后，要先判断“现在是不是该用某某 Skill”。这个判断依据主要是 Skill 的 name 和 description。第二关是参数抽取。一旦决定调用，模型就要从用户当前输入、对话历史甚至文件内容里，把 Skill 需要的参数一个个提取出来。第三关是指令执行。参数齐了之后，模型才会按照 Skill 内部的 instructions 去生成结果。第四关是结果返回。模型要把 Skill 产生的结果拼装回主对话流程，再给用户一个完整答复。

四道关卡里任何一环出了问题，你看到的外部表现都是同一个：AI 不听话。

1.3 为什么“写了”不等于“被执行”

很多人想不通：Skill 文件明明已经放进了指定目录，格式校验也过了，为什么模型还是不用？这里得先接受一个残酷的现实：在大多数 Agent 架构里，Skill 对模型来说只是“上下文中的一段文本”。模型本质还是在做文本续写，它从系统提示、历史对话、用户输入、Skill 内容以及各种工具描述中综合判断“接下来最合理的回复是什么”。

所以，Skill 不是程序 import 进来就必然执行，而是在“上下文竞争”中争取模型的注意力。如果其他指令更显眼、更具体，或者与 Skill 内容互相矛盾，模型就会选择忽略 Skill。搞明白这个底层逻辑，你就能理解接下来这四件事为什么这么重要。

2. 第一件事：触发描述没写对，AI 压根不知道什么时候该用

2.1 description 是触发开关，不是写给开发者的注释

我见过太多人把 Skill 的 description 当成“代码注释”来写，比如“这个 skill 用于处理文档”。这句话放到注释里没毛病，但放到 Skill 里基本等于没说。模型在决定要不要调用 Skill 时，主要就是读这段 description。它得像一个电梯推销语：在几个词之间说清楚“什么场景下、遇到什么需求时，你应该用我”。

打个比方，你让一个临时工在大厅里待命，告诉他要主动帮忙。结果他每次看到有人拿文件就去接，看到有人皱眉就去问要不要帮忙，忙活了半天却一件正事也没干。description 写得太宽，模型就是这个状态——任何请求都可能让它觉得“好像该调用一下”，结果真正的场景反而没处理好，因为它把精力都耗在了无关触发上。

2.2 常见的三种触发描述错误

根据我看到的实际教训，触发描述的错误基本可以归为三类。

第一类是过宽。描述写成“用于处理用户的请求”，那好了，AI 看什么都像需要用它，最后要么频繁误触发，要么因为触发太滥被对话逻辑限制住。第二类是过窄。描述写死成“当用户说‘请帮我整理会议纪要’时使用”，用户只要换一种说法，比如“把今天聊的内容归档一下”“记一下结论”，AI 就不触发了，因为字面匹配不上。第三类是抓错重点。描述里大篇幅介绍 Skill 能输出什么格式，却不写它适用的场景和用户意图。格式是后端关心的事，模型关心的是“这个场景是不是你管的”。

这三种错误可以同时出现在一个 Skill 上。尤其第三种最容易迷惑人：description 全在讲“我是做数据清洗的，输出为 CSV”，但不讲“用户要求整理 Excel、去重、统一格式时你要出现”。模型根本搭不上场景和 Skill 的连接。

2.3 怎么写触发描述：场景 + 意图 + 输入，一个都不能少

我后来总结的写法很简单，一个描述套一个公式：在什么场景下，用户带着什么目标来求助时，调用这个 Skill，需要提供哪些关键输入。

拿会议纪要场景举例。差劲的 description 是：

description: 整理会议纪要

稍微好一点的：

description: 当用户要求整理会议纪要时使用，输出结构化内容

比较靠谱的：

name: meeting_notes description: 当用户请求整理会议纪要、生成会议记录、总结讨论结论、归档会议要点时使用。适用于用户提供会议原始文字稿或要求对一段多轮对话进行摘要整理的场景。需要用户提供原始会议内容文本。

看出来区别没有？后者把场景、意图、输入都放进去了，而且写明了需要什么材料。模型看到“把这段对话整理成纪要”时，能清晰匹配上“会议文字稿 + 摘要整理”这个组合。写描述的时候，你还得站在用户角度想：用户最可能用哪几种说法来表达需求？把这几种说法自然揉进描述里，触发率会高很多。我自己的经验是：宁可触发范围稍微宽一点，也别窄到只有完全一致的措辞才能触发——宽了顶多多调用几次，窄了就是功能彻底失灵。

3. 第二件事：指令正文含糊，模型执行时必然“自由发挥”

3.1 万金油指令的问题：AI 不知道你要的“整理”长什么样

触发对了，参数也传进来了，接下来就看 instructions。大部分“AI 不按要求执行”的翻车现场，问题都出在这里：指令正文对人类来说“意思到了”，但对模型来说“发挥空间太大”。

我举个例子。会议室 Skill 里写了这么一句：

请根据提供的会议内容，整理一份会议纪要。

这句话错了吗？从语法看没错。但模型执行时会犯难：纪要要分几个部分？要不要写参会人？决议事项要不要单列？待办任务要不要分配到人？如果这些没有写清楚，模型只能自己猜。猜对了叫“智能”，猜错了就叫“不按要求执行”——本质上是你没把“要求”定义清楚。

3.2 拆解一条合格的指令：步骤、结构、格式缺一不可

我踩过几次坑之后，把 Skill 里的指令写作彻底改成了“步骤驱动”。不管多简单的功能，都拆成显式步骤。一个会议纪要 Skill 的指令核心，我一般会拆成这样：

执行步骤： 1. 读取用户提供的原始会议文本，识别主要发言人、讨论主题和关键时间点 2. 从原文中提取所有明确提出的决策事项，逐条列出，标注决策内容与提出人 3. 找出所有需要后续跟进的行动项，按“负责人 + 任务描述 + 截止时间”格式整理 4. 按照以下结构输出纪要： - 会议主题 - 参会人员（若原文未提及则注明，不自行猜测） - 讨论要点（每条要点不超过50字） - 决议事项 - 行动项（表格形式呈现） 5. 如果原文内容不足以满足上述任一结构，请在该部分明确写“原文未提供相关信息”

这样写，模型就能对着步骤一步步执行，而不是凭感觉自由发挥。这里面有个关键点：输出格式要说死。你不说“用表格”，模型可能给你排成一大段；你说了“表格形式”，它就知道用 Markdown 表格。所谓“按要求执行”，要求本身必须具体到模板级别。

3.3 检查指令与描述、参数之间有没有打架

指令含糊之外，还有一种很隐蔽的情况：Skill 自己内部打架。我见过一个数据分析 Skill，description 写得非常明确——用户上传 Excel 后做去重和聚合分析。但 instructions 里却写“先检查数据是否完整，不完整则建议用户重新上传”。结果呢，模型每次拿到数据都在纠结“数据到底完不完整”，反而把去重和聚合的主任务丢到一边。

我的排查方法是：把 name、description、instructions 三块内容拉出来，当一份完整合同读一遍。站在一个新人的角度，按这份合同能不能准确执行？如果其中任何一句话让你产生疑问“这跟前面说的不是一回事吗”，那就是冲突点，必须改。Skill 内部的逻辑自洽，是它能被执行的前提。

3.4 不要只写“不要”，要给“要怎么做”的替换路径

很多人调不出理想效果，就拼命加负面指令：“不要输出废话”“不要用口语”“不要超过三行”。模型确实会看到这些“不要”，但它不知道该怎么替代。更好的做法是给反例 + 正例。比如：

不要使用模糊表达。例如，不要说“尽快完成”，应该写出具体时间点；不要用口语，例如“搞定了”，应该写成“已完成”。

模型对“正例”的模仿能力远强于对“禁令”的执行能力。这条经验值对任何 Skill 都适用。

4. 第三件事：参数定义与真实需求错位

4.1 参数是模型填写的“输入表单”，错位信息害死人

Skill 的第三个高频“不听话”点，在参数定义上。很多平台里的 Skill 都支持声明输入参数，由模型从用户对话里抽取后填入。你可别小看这一步，参数定义就是一张表单设计：字段名、类型、必填标识、释义都影响模型能不能把数据准确装进去。

我见过一个特别无语的案例。有人给会议纪要 Skill 定义了两个参数：meeting_text（会议原文）和 speaker_list（参会人列表）。看起来没问题是吧？但问题在于，speaker_list 的表述是“参会人名单”，模型就以为这是用户手动填的，如果用户没有直接提供，它就自动生成一份“推测名单”，甚至把“张三、李四”当成参会人，哪怕原文根本没出现。最后纪要里凭空多出一堆不存在的人名。这不是模型蠢，是参数定义没说明“必须从原文中提取，原文未提及则标记为未知”。

4.2 参数定义的重点：类型、必填、枚举、默认值，一个都要抠

我整理了一个参数自查清单，现在写每个 Skill 都会过一遍：

第一，字段类型要严格。有些平台支持 string、integer、boolean、array、object 等类型，不要全用 string。比如人数用 integer，是否包含待办事项用 boolean，参会人用 array。类型定义得越准，模型抽取时越不容易出错。

第二，必填标识要认真标。该必填的不标，会导致模型在没有关键信息时也强行调用，产出垃圾结果；不该必填的标了必填，会导致 AI 一再追问用户，体验很糟糕。通常来说，核心内容字段设为必填，其它可选项都放宽。

第三，枚举值能约束就约束。比如会议纪要的“纪要语言”参数，可以在枚举里限定为中文、英文、双语，而不是让模型自己发挥。你给了枚举，它就不会在输出里冒出日语。

第四，默认值要及时兜底。比如“输出详细程度”的默认值设为“标准”，模型拿不到用户偏好时至少有一个基准。

一个规范的参数定义长这样：

parameters: - name: meeting_text type: string description: 用户提供的会议原始文本内容，包括发言、讨论和结论 required: true - name: speaker_list type: array description: 从会议原文中提取的参会人员名单。原文未提及任何人员时，输出空数组 required: false - name: output_language type: string enum: [中文, English, 双语] default: 中文 required: false

注意看 speaker_list 的描述，我明确写了“从原文中提取”和“未提及则输出空数组”。这一句话就能堵住模型瞎编参会人这个坑。

4.3 参数和指令必须联动，否则等于白发

最后一个容易被忽略的检查点：所有声明的参数，在指令里有没有被真正使用到。我之前调试一个 Skill，定义了一个 output_format 参数，但 instructions 里从头到尾没提它。结果模型填了这个参数，却根本不按它执行——因为指令里没有引用这个参数的逻辑。参数和指令是联动的，参数是输入的容器，指令才是使用容器的过程。定义了一个参数却在指令里不提它，就相当于给临时工发了一张表格，但交代工作时根本没让他填。

所以每次写完参数，我都会到指令正文里用关键词搜一遍，确保每个参数至少被引用一次。没被引用的参数，要么删掉，要么补上对应逻辑。

5. 第四件事：你根本没确认 Skill 到底有没有被真正调用

5.1 只看“结果还行”，很容易误判

很多时候“AI 不按要求执行”是个假象。你以为是它执行了 Skill 但没做好，实际上它压根没调用 Skill，而是凭借自己的通用能力，假装完成了类似的事。这在一些场景里尤其隐蔽：你要的是一份规范格式的会议纪要，模型没用你的 Skill，直接自己编了一份纪要。看起来“结果还行”，但格式、步骤完全不是你写的那套。

我最初的排查方式就是只看结果，结果白白浪费了大量时间去改指令，却不知道问题在调用链路上。后面学乖了：只要发现生成结果跟 Skill 定义的格式不完全一致，第一反应是去查调用记录，而不是改指令。

5.2 打开调用日志与追踪，确认四道关卡

现在绝大多数 Agent 开发框架都支持日志输出或追踪功能。排查时我会抓两类信息。第一类是“模型是否发起了工具/技能调用”。在日志里对应着类似 tool_use 或 skill_invocation 的事件，里面会带 Skill 名称和调用参数，这一步对应触发识别和参数抽取两关。第二类是“调用之后的结果”。对应指令执行和结果返回两关，重点看返回值有没有被后续对话真正引用。

如果你用的框架没有现成追踪，可以自己加一层非常简单的日志：在 Skill 入口和出口各写一条标准日志，记录入参和出参。然后再故意触发一次，看入口日志有没有出现。没出现，说明模型根本没调用；出现了，说明后面几关有问题。这套排查法能直接缩小问题范围。

5.3 上下文溢出与技能丢失：长对话里的隐形杀手

还有一种特别容易踩的坑，发生在长对话和多轮请求场景。模型上下文窗口是有限的，Skill 文件内容是一开始加载进上下文的。随着对话变长、附件变多、系统提示占空间，早期注入的 Skill 描述可能被截断。到后面几轮，Skill 信息已经在模型视野之外了，它自然就不“记得”有这个技能。

对付这种情况，我会做三件事：一是尽量精简 Skill 文件的正文，把废话删掉，只留必要步骤和参数定义，减少被截断的概率；二是把最关键的触发描述放在文件靠前的位置，保证即使被截断，模型也先看到核心信息；三是针对长对话任务，定期重新注入关键 Skill 描述，或者在关键节点提醒 Agent 当前可用的技能列表。

5.4 多 AI 协作场景：Skill 可能被“队友”干扰

现在很多项目都上多 Agent 协作，Skill 不只在单个 Agent 里被调用，还会跨 Agent 传递。这时候“不按要求执行”的原因更复杂：主 Agent 可能调用了子 Agent 的服务，但子 Agent 没有加载对应的 Skill；或者一个子 Agent 的执行结果被另一个 Agent 改写，导致最终输出偏离了原始 Skill 的要求。

排查这类问题，就不能只看自己写的 Skill 了，要看整个协作链路上每个环节做了什么事。我的经验是：先把每个 Agent 负责的 Skill 范围固定死，不要出现两个 Agent 都挂着类似功能的 Skill，那会让路由判断混乱。接着在关键交接点做好日志透传，每经过一个 Agent，就把“处理人、用的什么 Skill、改了哪些字段”记录下来。多 Agent 的问题，本质上就是链路问题，先定位再下结论。

6. 实操案例：把四件事全部踩了一遍的会议纪要 Skill

6.1 初始版本：一个“看起来没问题”的 Skill

为了让整套排查方法好落地，我把之前真实翻过车的一个会议纪要 Skill 简化出来，完整走一遍。

初始版本长这样：

name: meeting_notes description: 整理会议纪要 instructions: | 请根据用户提供的会议内容生成一份会议纪要，要求内容完整、结构清晰。 parameters: - name: content type: string required: true description: 会议内容

这个 Skill 从语法上看没毛病。但实际跑起来，AI 经常输出一大段冗长的流水账，没有决议清单，行动项也混在叙述里。用户问它“谁负责跟进这件事”，它还得重新翻一遍才能答上。典型的不“按要求”执行现场。

6.2 逐项排查与修复

按四件事的顺序过一遍。

第一件，触发描述。原版的“整理会议纪要”太窄了，用户说“把讨论结果总结一下”“记一下下一步谁做什么”时，模型都不认为该调用它。于是我把 description 改成上面提过的版本，把“总结讨论结论”“归档会议要点”“输出行动项”等常见说法都包含了进去。

第二件，指令正文。原版是典型的“万金油”。我把执行过程拆成了五步，并规定了输出结构和缺失信息处理方式。特别加了“未提供的信息不得瞎编”这一条，堵住模型脑补。

第三件，参数定义。原版只有一个 content 字段，太笼统。我扩展为 meeting_text、speaker_list、output_language 三个参数，并在描述里强调“原文未提及人员则输出空数组”“语言默认中文”。这让模型在抽取阶段不再自由发挥。

第四件，调用链路确认。我在这个 Skill 的入口和出口各加了一条日志，在测试环境里故意用多种说法触发。第一次测试“把这段讨论整理成纪要”发现入口日志没有出现，说明 description 匹配不到位，于是又调整了措辞；第二次测出模型虽然触发了，但 speaker_list 被填成了推测名单，于是改参数描述。没有这一步，我可能还在傻傻改指令。

6.3 修复后的完整 Skill 参考

最终可供参考的版本如下：

name: meeting_notes description: 当用户请求整理会议纪要、生成会议记录、总结讨论结论、归档会议要点时使用。适用于用户提供会议原始文字稿或要求对一段多轮对话进行摘要整理的场景。需要用户提供原始会议内容文本。 instructions: | 执行步骤： 1. 读取用户提供的原始会议文本，识别主要发言人、讨论主题和关键时间点 2. 从原文中提取所有明确提出的决策事项，逐条列出，标注决策内容与提出人 3. 找出所有需要后续跟进的行动项，按“负责人 + 任务描述 + 截止时间”格式整理 4. 如果原文未提及负责人、截止时间等关键信息，必须明确标注“原文未提供”，禁止自行推断 5. 按照以下结构输出纪要： - 会议主题 - 参会人员 - 讨论要点（每条要点不超过50字） - 决议事项 - 行动项（用Markdown表格呈现） 6. 最终输出语言遵循 output_language 参数，默认为中文 parameters: - name: meeting_text type: string description: 用户提供的会议原始文本内容，包括发言、讨论和结论 required: true - name: speaker_list type: array description: 从会议原文中提取的参会人员名单。原文未提及任何人员时，输出空数组 required: false - name: output_language type: string enum: [中文, English, 双语] default: 中文 required: false

6.4 修复前后的效果对比与分析

修复后在同一个测试集上跑，效果差异非常明显。模板化输出稳定出现，每条讨论要点都被压缩到 50 字以内，行动项统一落成表格，负责人缺失时会明确写“原文未提供”，而不是编一个名字出来。

这个案例最值得记的点是：修复过程中没有一行代码涉及模型调参，全部改动都是在 Skill 自身的文本结构里完成的。这也再次说明，AI Agent 时代的“编程”，本质是把意图表达清楚，而不是把逻辑写死。

7. 排查顺序总结与速查清单

如果现在你的 Skill 还是出问题，给我按下面这个顺序查，能少走一半弯路。

还有几个细节值得单独提一下。

第一，Skill 文件里别塞太多跟执行无关的说明。我发现有人喜欢把“设计理念”“历史变更记录”写进 Skill 文件，这些内容会稀释模型注意力，让它在执行时“分心”。控制篇幅，就是为了让核心指令更突出。

第二，修改之后一定要跑触发测试，不要只跑一次正例。我习惯每次至少准备五句不同说法的触发语，三句应该触发的，两句不应该触发的。防止过宽或者过窄。

第三，改完参数 schema 后，有必要看一次模型实际传参的样例。很多 Agent 框架里可以查看“函数调用的入参”，那里能看到模型真正填了什么值，参数描述写得再怎么漂亮，实际传参错了就得改。

我个人在实际操作中的体会是，排查 Skill 问题最忌讳“头痛医头”。很多人一看到 AI 不听话，立刻改指令，改到十几次心态就崩了。其实回到那四件事，一项一项过，大概率能在十分钟内找到病根。尤其是触发描述和调用日志这两环，是最容易被人忽略、又最影响结果的地方。这套方法帮我在好几个项目里省下了大量返工时间，希望也能帮你把 AI Agent 真正“调教”成你想要的样子。