1. 问题到底出在哪先别急着改 Skill 本身写过 Skill 的人大概都经历过这个场景你花了大半天把一份 Skill 文档打磨得自认为逻辑严密、步骤清晰满心期待地丢给 AI结果它要么压根没读要么读了一半就开始自由发挥要么执行到第三步突然拐弯去干了别的事。你盯着屏幕心里只有一个念头——“我写得这么清楚它为什么就是不照做”这个问题在 Claude Code、Agent 开发、多 AI 协作这些场景里出现得极其频繁。很多人第一反应是“是不是我的 Skill 写得不够好”然后开始反复改措辞、加约束、堆例子改到第十版发现效果还是不稳定。但实际情况往往是问题不在 Skill 的内容本身而在 Skill 有没有被正确加载、有没有被正确触发、上下文有没有把它挤掉、以及它的结构是否适配模型的注意力机制。这四个方向基本覆盖了“Skill 写好但 AI 不执行”的绝大多数原因。我把它总结成一张排查清单按优先级从高到低排列排查顺序排查方向典型症状排查成本第一件Skill 是否真的被加载AI 完全不知道有这个 Skill极低第二件触发条件是否命中AI 知道有但没主动调用低第三件上下文是否被挤占有时执行有时不执行中第四件Skill 结构是否适配执行了但步骤错乱、遗漏中高这个顺序不是随便排的。先确认“有没有”再确认“触没触发”然后确认“有没有被干扰”最后才去优化“内容本身”。很多人一上来就跳到第四步改内容结果前三步的问题一个没解决改再多措辞也是白费。下面我按这四件事逐一拆开讲每一件都会说清楚怎么判断是不是这个问题、背后的机制是什么、以及具体怎么修。2. 第一件事Skill 到底有没有被加载这是最基础也最容易被忽略的一环。你写了一个 Skill 文件放在某个目录里但 AI 运行时根本没读到它——这种情况下你后面所有的优化都是空中楼阁。2.1 加载机制的基本原理不同平台的 Skill 加载机制不一样但核心逻辑大同小异。以 Claude Code 为例Skill 通常以文件形式存在于特定目录比如.claude/skills/或项目根目录下的约定位置运行时系统会扫描这些目录把 Skill 的元信息名称、描述、触发条件注入到模型的上下文中而 Skill 的完整内容则在被触发时才动态加载。这里有个关键点很多人没意识到元信息和完整内容是分开加载的。系统先让模型“知道有这么个 Skill”等模型判断需要用了才把完整内容读进来。所以如果你的 Skill 连元信息都没被扫描到模型压根不知道它存在自然不可能执行。常见的加载失败原因有这么几类路径不对文件放错了目录或者目录层级不符合平台约定格式不对文件扩展名、头部元数据格式不符合要求命名冲突多个 Skill 重名导致其中一个被覆盖权限问题文件没有读取权限或者所在目录被排除在扫描范围外缓存未刷新Skill 是新增的但运行时用的是旧缓存2.2 怎么确认 Skill 被加载了最直接的验证方法是让 AI 列出它当前知道的 Skill。你可以直接问“你现在能识别到哪些 Skill”或者“列出你可用的所有技能。”如果 AI 能准确说出你的 Skill 名称和描述说明元信息加载成功。如果它一脸茫然那就是加载环节出了问题。另一个方法是看日志。Claude Code 这类工具在启动时通常会输出加载了哪些 Skill、扫描了哪些目录。如果你能看到类似Loaded skill: xxx的输出基本可以确认加载成功。看不到的话就要去检查目录配置和文件格式。还有一个更隐蔽的情况Skill 被加载了但被更高优先级的配置覆盖了。比如你在项目级和用户级都放了同名 Skill系统可能只加载了其中一个。这种情况下 AI 会说“我知道这个 Skill”但实际用的是另一个版本的内容导致行为和你预期不符。提示每次新增或修改 Skill 后养成重启会话或手动刷新缓存的习惯。很多“改了没生效”的问题根源就是缓存没刷新。2.3 加载环节的实操检查清单我整理了一个快速检查流程按顺序走一遍基本能定位问题确认文件位置对照平台文档确认 Skill 文件放在正确的目录下确认文件格式检查扩展名、头部元数据如 name、description、trigger 等字段是否符合规范确认无重名搜索一下是否有同名 Skill 存在于其他目录确认权限用命令行确认文件可读目录未被排除重启验证重启会话直接问 AI 能否识别到该 Skill查看日志如果平台有加载日志检查是否有报错或跳过记录这六步走完加载问题基本能排除。如果确认加载没问题那就进入第二件事。3. 第二件事触发条件有没有命中Skill 被加载了不代表它会被调用。模型需要在合适的时机判断“现在该用这个 Skill 了”才会去读取完整内容并执行。如果触发条件设计得不好模型可能压根想不到要用它。3.1 触发是怎么发生的模型决定是否调用一个 Skill主要看两样东西Skill 的描述和当前对话的上下文。描述里写清楚了“什么时候该用我”模型在遇到类似场景时就会去匹配。如果描述写得模糊、宽泛或者和实际使用场景对不上模型就可能错过。举个例子你写了一个“代码审查 Skill”描述是“用于审查代码”。这个描述太泛了模型在遇到“帮我看看这段代码有没有问题”时可能觉得这只是一般性提问不一定要动用 Skill。但如果你把描述改成“当用户要求审查代码质量、检查潜在 bug、或评估代码规范时使用”命中率会明显提升。触发失败的典型表现是AI 知道有这个 Skill但在你期望它用的时候没用而是用自己的通用能力直接回答了。你事后问它“为什么不用那个 Skill”它可能会说“我觉得直接回答也可以”或者“我没意识到这个场景需要用到它”。3.2 描述写法的几个关键原则触发描述不是越详细越好也不是越短越好关键是要精准匹配使用场景。我总结了几个实操原则用场景语言不用功能语言写“当用户要求 X 时使用”而不是“这个 Skill 能做什么”覆盖同义表达用户可能用不同说法描述同一件事描述里要尽量覆盖这些变体明确排除条件如果某些场景不该用这个 Skill也要写清楚避免误触发避免过于宽泛描述太泛会导致模型频繁调用反而干扰正常对话避免过于狭窄描述太窄会导致该用的时候不触发Skill 形同虚设这里有个常见的误区很多人把 Skill 描述写成了功能说明书比如“本 Skill 提供代码审查功能支持多种语言能检查语法错误、逻辑问题、性能隐患……”这种写法对模型来说信息量很大但触发判断靠的不是功能列表而是“什么场景下该用”。功能描述可以放在 Skill 正文里触发描述要聚焦在场景匹配上。3.3 提高触发率的实操技巧除了描述本身还有几个技巧能提高触发率在对话中主动引导。如果你发现 AI 没主动用 Skill可以在提问时加一句“用 XXX Skill 来处理这个”。这样模型会明确知道该调用哪个 Skill。虽然这看起来像是“手动触发”但在调试阶段非常有用能帮你确认 Skill 本身没问题只是触发条件没命中。设置明确的触发关键词。有些平台支持在 Skill 配置里设置触发词比如当用户输入包含“审查”“检查”“review”等词时自动关联。如果你的平台支持这个功能一定要用上。测试不同表述方式。同一个需求换几种说法分别测试看哪种能触发、哪种不能。这样能帮你找到描述的盲区针对性补充。注意触发率不是越高越好。如果一个 Skill 被频繁误触发会干扰正常对话流程用户体验反而更差。目标是“该用的时候用不该用的时候不用”。4. 第三件事上下文有没有把 Skill 挤掉这是最隐蔽也最容易被忽视的问题。Skill 加载了触发条件也命中了但执行到一半 AI 突然“忘了” Skill 的内容开始自由发挥。这种情况多半是上下文被挤占了。4.1 上下文窗口的竞争关系模型的上下文窗口是有限的。对话历史、系统提示、加载的 Skill 内容、工具返回结果、用户当前输入——这些东西全都在抢同一块空间。当上下文快满的时候系统会做截断或压缩而 Skill 内容往往是最容易被牺牲的部分因为它通常比较长而且看起来“不那么紧急”。这就解释了一个很常见的现象对话刚开始时 Skill 执行得好好的聊了十几轮之后 AI 就开始不按 Skill 来了。不是 Skill 坏了是它被挤出上下文了。还有一种情况是多个 Skill 同时加载。如果你有五个 Skill每个都几千字加起来可能就把上下文占了一大半。模型在处理当前任务时可能只保留了最近用到的那个 Skill 的内容其他的被压缩掉了。4.2 怎么判断是不是上下文问题判断方法很简单看问题是否和对话长度相关。如果新建一个会话同样的 Skill 执行正常但在长对话里就不行那基本可以确定是上下文挤占。另一个信号是 AI 的回答开始变得“泛化”。它不再严格按照 Skill 里的步骤走而是给出一个笼统的、像是通用回答的内容。这说明它可能已经看不到 Skill 的详细内容了只能凭记忆或通用知识来回答。还有一种表现是“选择性遗忘”。Skill 里有十个步骤AI 执行了前五个后面五个跳过了或者合并了。这也是上下文被压缩的典型症状——前面的内容还在后面的被截掉了。4.3 缓解上下文挤占的实操方法控制 Skill 长度。这是最根本的方法。Skill 不是越长越好能精简就精简。把不必要的内容删掉把详细说明放到外部文档里Skill 正文只保留核心步骤和关键约束。一个 Skill 控制在几百到一千字以内比写几千字效果更好。拆分 Skill。如果一个 Skill 承担了太多职责考虑拆成多个小 Skill按需加载。这样每次只加载当前需要的那部分减少上下文占用。及时清理对话历史。长对话中如果前面的内容已经不再需要可以主动开启新会话或者使用平台提供的上下文清理功能。不要让无关的历史信息一直占着空间。把关键约束前置。如果 Skill 里有几条必须遵守的硬性规则把它们放在最前面并且用醒目的格式标出来。这样即使上下文被压缩这些关键信息也更有可能被保留。用外部文件承载细节。Skill 正文只写“做什么”和“关键约束”具体的参考文档、示例、详细说明放到外部文件里需要时再读取。这样 Skill 本身很短不容易被挤掉。提示上下文挤占是动态发生的同样的 Skill 在不同对话长度下表现可能完全不同。测试 Skill 时一定要在长对话场景下也验证一遍。5. 第四件事Skill 结构是否适配模型的注意力前三件事都排除了Skill 也确实在执行但执行结果还是不理想——步骤错乱、遗漏关键点、格式不对。这时候就要看 Skill 本身的结构了。不是内容不对而是组织方式不适配模型的注意力机制。5.1 模型是怎么“读” Skill 的模型读 Skill 不像人读文档那样从头到尾线性理解。它更像是在做注意力分配——哪些内容权重高哪些权重低。影响权重的因素包括位置开头和结尾权重高、格式加粗、列表、标题会提升权重、重复次数、以及和当前任务的关联度。这意味着如果你把关键步骤埋在一大段文字中间模型很可能“看漏”。如果你用大段散文式描述模型可能抓不住重点。如果你把约束条件写在最后模型可能读到一半就开始了。一个典型的反例是这样的 Skill 写法首先你需要检查代码的语法然后看看有没有逻辑问题顺便注意一下性能另外代码风格也要统一还有记得检查注释是否完整最后别忘了看看有没有安全隐患……这段话人读起来没问题但模型读的时候注意力会被分散到各个点上没有一个明确的优先级。结果就是它可能只做了其中几项漏掉其他的。5.2 结构化写法的几个实操要点用编号列表代替段落。把步骤写成 1、2、3、4模型对编号列表的遵循度明显高于散文。每个步骤独立成行不要挤在一起。关键约束用加粗或独立段落。比如“必须使用 XXX 格式”“禁止执行 XXX 操作”这类硬性约束要单独拎出来不要混在普通描述里。步骤之间用空行分隔。视觉上的分隔会帮助模型区分不同的步骤减少混淆。把最重要的放在最前面和最后面。模型对开头和结尾的注意力最高。核心约束放开头关键提醒放结尾中间放具体步骤。避免嵌套过深。三层以上的嵌套列表会让模型难以跟踪层级关系。如果需要嵌套尽量控制在两层以内。用表格对比多个选项。如果 Skill 里涉及“根据情况选择 A 或 B”用表格列出条件和对应选择比用文字描述更清晰。5.3 一个结构化 Skill 的参考模板下面是一个简化后的 Skill 结构模板可以作为参考# Skill 名称 ## 触发条件 当用户要求 [具体场景] 时使用。 ## 核心约束 - 必须 [约束1] - 禁止 [约束2] - 输出格式必须为 [格式] ## 执行步骤 1. 第一步[具体操作] 2. 第二步[具体操作] 3. 第三步[具体操作] ## 输出要求 - [要求1] - [要求2] ## 异常处理 如果遇到 [情况]则 [处理方式]。这个模板的好处是触发条件明确、约束前置、步骤清晰、输出要求独立、异常处理有兜底。模型读起来注意力分配均匀不容易漏掉关键信息。5.4 测试与迭代的方法Skill 结构优化不是一次性的需要反复测试。我的做法是准备一组测试用例覆盖正常场景、边界场景、异常场景每次只改一个变量比如只调整步骤顺序或只改约束位置不要一次改多处记录每次结果哪个版本执行准确率高哪个版本容易漏步骤在长对话中复测短对话表现好不代表长对话也好换不同表述测试同一个需求换几种说法看触发和执行是否稳定这个过程听起来繁琐但比起盲目改措辞效率高得多。通常迭代三到五轮就能找到一个比较稳定的结构。6. 常见问题速查与避坑经验前面四件事讲完了这里整理一份速查表方便你在遇到问题时快速定位。同时补充几个我踩过的坑都是文档里不会写但实际很常见的。6.1 问题速查表症状最可能的原因优先排查AI 完全不知道有 Skill加载失败文件路径、格式、权限AI 知道但不用触发条件没命中描述写法、触发词短对话正常长对话失效上下文挤占Skill 长度、对话历史执行了但步骤错乱结构不适配编号、格式、约束位置有时执行有时不执行触发不稳定或上下文波动描述精准度、上下文长度执行结果格式不对输出要求不明确独立输出要求段落多个 Skill 互相干扰触发条件重叠描述差异化、优先级设置6.2 几个容易踩的坑坑一把 Skill 当文档写。很多人写 Skill 像写技术文档追求全面、详细、面面俱到。但模型不是人它不需要那么多背景信息。Skill 要的是精准、简洁、可执行。写完之后问自己一句如果只能保留三句话是哪三句把这三句放在最显眼的位置。坑二忽略平台差异。不同平台对 Skill 的加载机制、触发方式、上下文管理都不一样。在 A 平台好用的 Skill搬到 B 平台可能完全失效。跨平台使用时一定要重新验证加载和触发。坑三一次加载太多 Skill。有人喜欢把所有 Skill 都开着觉得这样 AI 能力更强。实际上 Skill 越多上下文竞争越激烈每个 Skill 的执行质量都会下降。按需加载用完就关效果反而更好。坑四不测试边界情况。正常场景下 Skill 执行得好不代表边界场景也没问题。比如用户输入不完整、需求模糊、或者同时涉及多个 Skill 的场景都需要专门测试。坑五改了不重启。很多平台会缓存 Skill 内容改了文件但不重启会话用的还是旧版本。这个坑我踩过不止一次排查半天发现是缓存问题。6.3 一个实用的调试流程最后分享一个我常用的调试流程按这个顺序走基本能覆盖大部分问题新建会话确认 Skill 被加载问 AI 能否识别用标准表述触发 Skill确认能正常执行换几种表述测试触发稳定性在长对话中测试执行一致性检查输出格式是否符合要求测试边界场景看异常处理是否生效如果以上都通过再考虑优化 Skill 内容本身这个流程的核心逻辑是先排除环境问题再排除触发问题最后才动内容。顺序反了就会陷入“改了没用不知道为什么没用”的死循环。我个人在实际操作中的体会是Skill 调试最忌讳的就是“凭感觉改”。看到 AI 不执行第一反应是改措辞改完发现还是不行再改再不行。折腾半天其实问题可能只是文件放错了目录。按这四件事的顺序排查能省下大量时间也能让 Skill 的稳定性上一个台阶。