1. 先搞清楚“不执行”到底卡在哪一层Skill 写好了AI 却像没看见一样该走的流程不走该调的接口不调该输出的格式全乱。这个问题我前前后后踩了不下十次坑从最早的 Claude Code 自定义 skill到后来自己搭 agent 框架做多步任务编排几乎每一种“技能加载失败”的姿势都见过一遍。先说结论绝大多数情况下问题不在模型能力而在技能本身的结构、触发条件、上下文注入方式或者运行环境的配置上。这四件事按顺序查一遍能解决九成以上的“AI 不按要求执行”。这篇文章适合两类人看。一类是刚接触 skill 机制、在 Claude Code 或者类似 agent 工具里写自定义技能的开发者另一类是已经在做 agent 项目、发现技能时灵时不灵、想系统排查的工程师。我会把每个排查点的原理讲清楚再给可直接复现的操作步骤和参数最后附上我自己的避坑清单。全文基于实际项目经验不是文档翻译。先对齐一个基础认知。所谓 skill本质上就是一段结构化的指令包它告诉 AI 在什么场景下、按什么顺序、用什么工具、输出什么格式。它和普通的 prompt 最大的区别在于skill 通常带有触发条件什么时候加载、执行步骤怎么做、依赖声明需要哪些工具或权限和输出约束结果长什么样。任何一环出问题AI 都会表现得像“没看到这个 skill”。我习惯把排查分成四层从外到内依次是加载层、触发层、上下文层、执行层。下面逐个拆。2. 第一件事Skill 到底有没有被加载进来这是最容易被忽略的一层。很多人写完 skill 文件往目录里一放就默认 AI 能读到。实际上不同工具的加载机制差别很大Claude Code、VS Code 插件、自建 agent 框架各有各的规则。2.1 加载路径和文件命名规则以 Claude Code 为例skill 通常放在项目根目录下的特定文件夹里文件名和扩展名都有讲究。我见过最常见的错误是文件放对了目录但命名不符合规范导致扫描时被直接跳过。比如有的工具要求 skill 文件必须是特定后缀有的要求文件名全小写加连字符有的要求每个 skill 必须有一个同名的元数据文件。排查方法很直接先确认你的工具到底从哪些路径加载 skill。这个信息一般在工具的配置文档或者启动日志里。Claude Code 启动时如果开了 verbose 模式会打印它扫描了哪些目录、加载了哪些 skill。如果你在日志里看不到自己的 skill 名字那后面所有排查都是白费。# 以 Claude Code 为例启动时观察加载日志 claude --verbose # 或者在项目里检查 skill 目录结构 ls -la .claude/skills/注意不同版本的 Claude Code 对 skill 目录的约定可能不同升级后一定要重新确认路径。我就遇到过一次在线升级最新版本之后skill 目录从旧路径迁移到新路径结果所有自定义 skill 集体失效。2.2 依赖和权限声明缺失Skill 被扫描到了不代表能被正常使用。如果 skill 里声明了需要调用某个工具、访问某个文件、执行某条命令但运行环境没有对应权限加载阶段就可能静默失败。这种失败最坑因为工具往往不报错只是把 skill 标记为“不可用”然后 AI 就当作没这个技能。我的做法是每写完一个 skill先做一个最小可执行验证。把 skill 简化到只剩一条最简单的指令比如“输出 hello”确认它能被加载和执行再逐步加回复杂逻辑。这样能把加载问题和逻辑问题彻底分开。排查项检查方法常见问题加载路径查看工具日志中的扫描目录路径写错、版本升级后路径变更文件命名对照工具规范检查后缀和命名大小写不符、缺少元数据文件依赖声明检查 skill 中引用的工具是否可用工具未安装、权限不足语法格式用工具自带的校验命令检查YAML 缩进错误、字段拼写错误2.3 一个真实的加载失败案例我之前写过一个用于代码审查的 skill逻辑很完整但死活不生效。查了两个小时最后发现是 skill 文件头部的元数据里description字段写成了中文而那个版本的加载器对非 ASCII 字符处理有 bug直接导致整个文件解析失败。改成英文描述后立刻正常。这件事给我的教训是skill 的元数据部分尽量用最保守的格式别用特殊字符、别用花哨的写法等确认能加载了再考虑优化可读性。3. 第二件事触发条件是不是根本没命中Skill 加载进来了但 AI 没用它第二个要查的就是触发条件。这是“AI 不按要求执行”里占比最高的原因没有之一。3.1 触发描述写得太窄或太宽每个 skill 都有一个触发描述告诉 AI 什么情况下该用这个技能。这个描述写得好不好直接决定命中率。写得太窄比如“当用户要求用 Python 3.11 在 Linux 环境下处理 CSV 文件时使用”那稍微换个场景 AI 就不认了。写得太宽比如“处理任何文件时使用”又会导致 AI 在不该用的时候乱用反而干扰正常流程。我的经验是触发描述要覆盖“意图”而不是“具体操作”。比如你要做一个数据清洗 skill触发描述应该围绕“用户需要清洗、整理、规范化数据”这类意图而不是绑定到某个具体文件格式或工具。同时在描述里列出几个典型的触发短语能显著提高命中率。# 触发描述示例覆盖意图列举典型场景 name:># 粗略估算上下文 token 占用的思路 def estimate_tokens(text): # 英文约 4 字符 1 token中文约 1.5 字符 1 token # 这里给一个保守估算 return len(text) / 3 skill_content open(skill.md).read() history get_conversation_history() tool_output get_last_tool_result() total estimate_tokens(skill_content history tool_output) print(f预估占用 token: {total}) # 如果接近模型上限的 80%就要考虑精简4.2 指令的优先级和位置AI 对上下文中不同位置的信息敏感度不一样。放在最前面的指令、放在最后的指令、以及被明确标记为“必须遵守”的指令权重更高。如果你的 skill 关键约束藏在中间一大段文字里AI 很可能忽略。我的做法是把最关键的输出格式约束和禁止事项放在 skill 的开头和结尾各强调一次。开头告诉 AI“这个 skill 的核心目标是什么”结尾再重申“输出必须满足哪些硬性要求”。中间放具体的执行步骤。这样即使中间部分被部分忽略头尾的约束还在。4.3 工具返回结果的污染如果 skill 执行过程中调用了工具工具返回的内容也会进入上下文。有些工具返回一大堆无关信息把 skill 的后续指令“淹没”了。比如你让 AI 查一个文件工具返回了整个目录的列表AI 的注意力就被带偏了。解决办法是在 skill 里明确要求工具调用的输出处理方式。比如“调用搜索工具后只提取前 5 条最相关结果忽略其他内容”。这样能主动控制进入上下文的噪声量。5. 第四件事执行阶段的工具调用和输出约束前三层都过了AI 确实在按 skill 执行但结果还是不对。最后一层要查的是执行本身——工具调用是否正确、输出格式是否被遵守。5.1 工具调用的参数错误Skill 里写了“调用 X 工具完成 Y”但 AI 实际调用时参数传错了。这种情况在工具接口复杂、参数多的时候特别常见。AI 可能把参数名记混或者把可选参数当必填导致调用失败然后它就自己编了一个结果。排查方法是打开工具的调用日志看 AI 实际传了什么参数。Claude Code 和一些 agent 框架都支持打印工具调用详情。对比 skill 里的预期和实际调用差异一目了然。# 查看工具调用日志的通用思路 # Claude Code 中可以通过调试模式观察 claude --debug # 自建 agent 框架一般在日志里记录 tool_call 和 tool_result grep tool_call agent.log | tail -205.2 输出格式约束不够硬“请用 JSON 格式输出”这种软约束AI 经常不遵守尤其是任务复杂的时候。它可能输出 JSON 外面包一层解释文字或者字段名对不上。要让输出格式真正被遵守得用硬约束给出完整的 schema、给出正例和反例、明确说明“只输出 JSON不要任何其他文字”。# 输出约束的写法对比 # 软约束容易失败 output: 请用 JSON 格式返回结果 # 硬约束成功率高 output: | 只输出一个 JSON 对象不要包含任何解释文字、markdown 代码块标记或前后缀。 格式必须严格如下 { status: success | failed, items: [{name: string, value: number}], summary: string } 错误示例在 JSON 前后添加 好的结果如下 这类文字。5.3 多步任务的中间状态丢失如果 skill 包含多个步骤AI 执行到第三步时可能忘了第一步的约束。这在长任务里很常见。解决办法是在每一步开始时重申当前步骤的目标和约束而不是只在开头说一次。我管这叫“步骤级上下文锚定”实测能显著降低长任务的跑偏率。执行阶段常见问题解决手段工具调用参数错误、调用失败后编造结果开启调用日志对比预期与实际输出格式软约束不遵守、格式漂移硬约束 正反例 只输出要求多步任务中间步骤遗忘约束每步重申目标和约束错误处理失败后不重试、直接放弃明确重试策略和降级方案6. 常见问题速查表与避坑清单把上面四层排查浓缩成一张速查表遇到问题按顺序过一遍。现象最可能的原因优先排查AI 完全无视 skill加载失败或触发未命中查加载日志、测触发用例AI 知道用 skill 但执行跑偏上下文被挤占或指令位置不佳估算 token、调整指令位置工具调用失败后编结果参数错误或权限不足查工具调用日志输出格式总是不对约束太软改硬约束、加正反例长任务中途遗忘中间状态丢失步骤级重申约束多 skill 时灵时不灵触发冲突建触发矩阵、排优先级几个我踩过的坑单独拎出来说。第一别在 skill 里写太长的背景介绍AI 不需要你解释这个技能为什么重要它需要的是清晰的执行指令。背景介绍占的每一个 token都是从执行指令那里抢来的。第二skill 的版本管理很重要我建议用 git 管理 skill 文件每次改动都提交出问题能快速回滚对比。第三测试 skill 要用真实任务别只用构造的简单用例真实任务的复杂度和噪声才是检验 skill 的唯一标准。还有一个容易被忽略的点不同模型对同一个 skill 的执行效果可能差很多。同一个 skill在 Claude 上跑得好换到别的模型可能就崩。如果你的 agent 支持多模型切换skill 要针对主力模型做优化同时给其他模型留降级方案。7. 我个人的排查顺序和工具习惯最后分享我自己的排查流程基本是固定动作。第一步看加载日志确认 skill 在不在。第二步跑触发测试集确认命中率。第三步开调试模式跑一个真实任务看上下文占用和工具调用。第四步检查输出格式约束。这四步走完九成问题都能定位。工具上我习惯在项目里放一个skill-debug.md记录每个 skill 的加载状态、触发测试结果、已知问题和修复记录。这个文件不参与运行纯粹是排查时的参考。时间长了你会发现很多问题是重复出现的有个记录能省大量时间。Skill 机制本身还在快速演进不同工具的实现差异很大今天能用的写法明天可能就变了。所以比起记住某个具体写法更重要的是理解这四层排查的逻辑加载、触发、上下文、执行。不管工具怎么变问题永远出在这四层里的某一层。把这套排查思路内化比背任何文档都管用。