1. 先别急着改 Skill问题大概率不在它身上写 Skill 这件事很多人第一次做都会经历一个完整的情绪周期兴致勃勃地写完满怀期待地测试结果 AI 完全不按套路出牌然后开始怀疑人生——是不是我 Skill 写得不够好是不是模型太笨是不是这个方案根本行不通我一开始也是这么想的。后来踩的坑多了才慢慢意识到Skill 写好了但 AI 不执行绝大多数情况下不是 Skill 本身的问题。这就像你给一个新员工写了一份非常详细的操作手册但他还是做错了——问题可能出在他根本没看到这份手册或者看到了但理解成了别的东西又或者他看到了、理解了但手头的工具不支持他这么做。所以每次遇到Skill 不生效的情况我现在都会按一个固定的顺序排查四件事。这个顺序不是随便定的而是按照从外到内、从粗到细的逻辑排列的——先确认最外层的加载问题再往里查触发、上下文和执行环境。大部分问题在前两步就能定位到真正需要改 Skill 内容的情况反而很少。这篇文章就把这四个排查方向拆开讲清楚每个方向我会说明为什么会出现这个问题、怎么快速验证、以及对应的修复思路。不管你是刚接触 Skill 概念的新手还是已经在 Agent 项目里写了一堆 Skill 的老手这套排查流程都能直接用。一个基本前提本文讨论的 Skill 指的是给 AI Agent 编写的结构化指令集或能力描述文件不是某个特定平台的专有功能。不同工具对 Skill 的叫法和实现方式不同但底层逻辑是相通的。2. 第一件事确认 Skill 到底有没有被加载这是最容易被忽略、但出现频率最高的一个问题。你写了一个 Skill 文件放在某个目录里满心以为 AI 会自动读取但实际上它压根没被加载进去。2.1 Skill 的加载机制是什么样的不同的 Agent 框架对 Skill 的加载方式不一样但大致可以分成三类自动扫描型框架启动时扫描指定目录下的所有 Skill 文件自动注册。比如某些 Claude Code 的配置方式会把特定目录下的 markdown 文件当作 Skill 自动加载。显式注册型需要在配置文件里手动声明每个 Skill 的路径和名称不声明就不会被加载。动态调用型Skill 不会预先加载而是在对话过程中根据意图匹配动态检索。这种方式下Skill 文件存在不等于会被用到。你得先搞清楚自己用的框架属于哪一种。我见过太多人把 Skill 文件往目录里一扔就完事了结果那个框架是显式注册型的根本没被加载进去。2.2 怎么验证 Skill 是否已加载最直接的办法是问 AI 本身。在对话里直接问你现在有哪些可用的 Skill请列出名称和简要描述。如果 AI 能准确列出你写的 Skill说明加载没问题。如果它说没有或者列出来的东西对不上那就是加载环节出了问题。另一个办法是看日志。大部分 Agent 框架在启动时会有加载日志告诉你哪些 Skill 被成功注册、哪些被跳过、哪些报错了。这个日志信息非常关键但很多人从来不看的。还有一种情况是 Skill 加载了但被截断了。比如你的 Skill 文件写了两千字但框架只加载了前五百字后面的内容直接被丢弃。这种问题最隐蔽因为 AI 确实知道有这个 Skill但只知道一部分。2.3 加载失败的常见原因问题类型具体表现排查方法路径错误Skill 文件不在框架扫描的目录下检查框架文档确认扫描路径格式不符文件格式不是框架要求的类型确认是 md、yaml 还是 json命名冲突多个 Skill 同名导致覆盖检查是否有重复命名编码问题文件编码不是 UTF-8用 file 命令检查编码权限不足框架没有读取该文件的权限检查文件权限设置长度超限Skill 内容超出框架限制被截断查看加载日志中的警告信息我自己的习惯是每次新建一个 Skill 之后第一件事就是验证它有没有被正确加载。这个步骤花不了两分钟但能省掉后面大量的无效调试时间。3. 第二件事Skill 被加载了但触发条件没对上确认 Skill 已经加载之后下一个要排查的就是触发问题。Skill 加载了不代表它会被用到——很多框架需要满足特定条件才会激活某个 Skill。3.1 触发机制的三种常见模式关键词触发是最简单的一种。你的 Skill 里定义了某些关键词当用户的输入包含这些关键词时Skill 被激活。这种模式的问题在于用户的实际表达方式可能和你预设的关键词差很远。比如你设了数据分析作为触发词但用户说的是帮我看看这组数字那就触发不了。意图匹配触发稍微智能一些。框架会根据用户输入的语义来判断意图然后匹配对应的 Skill。这种方式对表达方式的容忍度更高但依赖框架的意图识别能力。如果意图识别不准Skill 照样不会被触发。显式调用触发是最可控的。用户或上游系统需要明确指定使用哪个 Skill。这种方式不会有误触发的问题但对使用者有要求——得知道有哪些 Skill 可用。3.2 为什么明明说了相关的话却没触发这个问题的根源往往在于描述和实际语义之间的鸿沟。你在 Skill 的 description 字段里写的是用于处理数据可视化任务但用户说的是帮我把这些数据画成图。从人的角度看这两句话是一回事但对意图匹配系统来说可能就差了几个关键token的距离。解决办法是在 Skill 的描述里尽可能覆盖多种表达方式。不要只写专业术语也要包含口语化的说法。比如name:>