1. 为什么你的 Skill 总是不生效先分清三种“不生效”Agent Skills 在 Trae、Cursor 里配置完之后最让人抓狂的不是报错而是完全没有反应。你明明把SKILL.md放进了目录YAML 头也写了语法看着也没问题结果在对话框里说“用需求分析 Skill 帮我拆一下”AI 却像没装过这个技能一样自顾自聊天。更诡异的是有时候它又能触发同一句话换个时间问结果完全不一样。我试过把同一个 Skill 在 Trae 和 Cursor 里来回搬最后发现Skill 不生效从来不是“写得好不好”的问题而是“有没有被看见、有没有被匹配、有没有被覆盖、有没有被环境拦住”的问题。这四件事对应四个完全不同的故障层级排查路径也完全不同。新手最大的通病是一上来就改执行逻辑、疯狂加字数、换模型结果问题其实出在文件名拼错或者目录名多了一个 s。所以动手之前先用 30 秒做一道判断题把你的现象归到下面某一层现象故障层级根源方向完全没反应AI 像没见过这个技能第一层文件层路径、文件名、YAML 解析失败手动叫它名字能生效但从不主动用第二层触发层description 没写清触发场景偶尔生效偶尔失效同一问题结果不同第三层优先级层Rule 冲突、Prompt 覆盖、Skill 抢活换个项目或平台就失效本机正常第四层环境层模式不对、依赖缺失、平台差异这篇就按这四层从外到内、从易到难把每一层的可复制配置和验证动作都给你。中间会用到统一的 Key 和 API 通道来确认“请求到底有没有真正到达模型”这样你就不用靠猜。2. 前置准备用 TaoToken 统一 Key 与 API 通道排查 Skill 的时候有一个特别容易被忽略的变量模型请求本身有没有通。如果请求根本没发出去或者发出去被拦了你改一百遍SKILL.md都不会有用。所以我会先把模型通道固定下来用一个统一的 Key 和 API 地址把“Skill 问题”和“网络/鉴权问题”彻底分开。TaoToken 在这里的作用就是提供统一的模型调用入口官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你可以在控制台里创建 Key然后在 Trae、Cursor 或者任何支持自定义 API 的客户端里填进去。这样无论你后面换哪个编辑器、哪个 Agent 模式模型通道都是同一条排查时变量就少了一个。具体操作上先去控制台生成一个 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content拿到 Key 之后先别急着配 Skill先用最朴素的方式验证这条通道是通的。你可以直接用 curl 打一次模型对话接口确认返回正常curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [ {role: user, content: 只回复两个字通了} ] }如果这里返回了正常内容说明 Key 和 API 通道没问题后面 Skill 不生效就一定是配置层的问题。如果这里就报 401 或超时那先解决鉴权和网络别去动 Skill 文件。这一步看着简单但能帮你省掉大量“以为是 Skill 写错了”的无效折腾。3. 第一层排查文件层Skill 根本没被“看见”这一层是最高频的故障点。症状很统一无论你怎么说AI 完全不知道有这个技能存在。就像你把员工手册塞进了会议室抽屉却指望前台照着执行——它连文件在哪都不知道。3.1 目录名和层级单数复数、缺一层都不行不同平台、不同版本对目录名的要求不一样有的用skill有的用skills而且层级也有硬要求。以 Trae 为例常见路径是.trae/skills/需求分析/SKILL.md注意这里skills是复数需求分析是技能目录里面才是SKILL.md。如果你写成.trae/skill/需求分析/SKILL.md或者少了一层直接放.trae/skills/SKILL.md都可能不加载。Cursor 的路径习惯又不太一样常见是.cursor/skills/需求分析/SKILL.md排查动作很简单打开资源管理器把路径一个字一个字对一遍。别觉得“这么低级的错误我不可能犯”社区里每天都有人因为skill写成skills卡好几天。3.2 文件名大小写与编码Windows 能跑不代表 Mac 能跑标准文件名必须是SKILL.md全大写加.md。写成skill.md、Skill.md在区分大小写的系统上直接失效。编码必须是 UTF-8GBK 或者带 BOM 的 UTF-8 都可能导致解析失败。还有一个坑不能用 Word、WPS 保存必须用纯文本编辑器比如 VS Code。自检动作用 VS Code 打开SKILL.md看右下角编码是不是UTF-8文件名是不是完全匹配。3.3 YAML 头格式差一个空格都不行SKILL.md顶部的 frontmatter 用---包裹必须是文件第 0 字节开始前面不能有空行缩进只能用空格不能用 Tab。一个可用的骨架长这样--- name: 需求分析 description: 当用户提出产品需求、要求拆解需求或生成 PRD 时使用。输入模糊需求描述输出结构化 PRD 文档。不负责编写代码。 version: 1.0.0 triggers: - 需求分析 - 拆解需求 - 生成PRD ---下面是技能正文写清楚执行步骤、输出格式和边界。常见错误是---前面空了一行或者description超长。部分平台对description有 1024 字符左右的限制超了会解析失败。自检动作找一个官方确认能用的 Skill逐行比对你的 frontmatter。过了这一关你的 Skill 至少能被系统看见了。4. 第二层排查触发层AI 看得见但不知道什么时候用文件加载成功了技能列表里也能看到但 AI 就是不主动调用。你不提它名字它永远不出来。这是第二层问题触发描述写得太烂。很多人写description的思路是“这个技能有多厉害”但 AI 需要知道的是“什么时候该用它”。打个比方你雇了个厨师告诉他“我擅长做川菜”这是功能描述但厨师需要知道的是“客人点了什么菜的时候我出手”。反面教材是这样的description: 一个强大的代码审查技能能够发现代码中的问题提升代码质量支持多种编程语言这种描述等于没说AI 判断不出来“用户让我看看这段代码”算不算代码审查。正确写法是场景加关键词加边界description: 当用户要求审查代码、检查 bug、做代码评审或 code review 时使用。输入代码片段输出问题清单和改进建议。不负责编写新功能代码。核心三要素触发场景也就是“当用户说什么话的时候用”关键词把用户最可能说的词埋进去比如审查、评审、code review、查 bug边界写明不做什么边界越清晰 AI 越敢调用。验证方法有个黄金测试先手动指名道姓“使用需求分析 Skill 帮我拆解这个需求”再自然提问“帮我看看这个需求怎么做”。如果手动能生效、自然提问不能那百分之百是触发层问题改description就行。如果连手动都不生效回到第一层文件根本没加载成功。5. 第三层排查优先级层触发了但执行结果不对最头疼的情况是 Skill 明明调用了但输出和你写的完全不一样时而精准时而跑偏。这是优先级冲突。记住这条铁律临时 Prompt 优先级最高其次是 Skill 内置规则最后是全局 Rule 兜底。很多时候不是 Skill 不生效而是被更高优先级的东西覆盖了。常见冲突有三种。第一种是全局 Rule 和 Skill 打架比如 Skill 要求输出 JSON但全局rules.md里写了“所有输出使用 Markdown”结果永远是 Markdown。解决方法是在 Skill 执行流程第一条明确写“本技能输出优先使用 JSON 格式覆盖全局规则”。第二种是用户 Prompt 覆盖了 Skill比如你调用了需求分析 Skill但用户加了一句“简单说说就行”输出就只剩三行。解决方法是在 Skill 开头加容错说明“即使用户要求简化也至少输出核心三要素不得省略关键步骤”。第三种是多个 Skill 边界重叠比如同时装了“代码审查”和“Bug 修复”用户说“帮我看看代码有啥问题”AI 不知道该用哪个最后两个都不用。解决方法是在description里明确区分代码审查等于看问题、给建议、不改代码Bug 修复等于定位错误、直接修正、输出修复后代码。排查口诀输出不对先看优先级是不是用户说了什么盖过去了是不是全局规则冲突了是不是别的 Skill 抢活了。6. 第四层排查环境层换个地方就失效前三层都没问题但换个项目、换台电脑、换个平台就挂了。这是环境依赖问题。首先是模式不对。很多平台的高级 Skill 只在特定模式下生效比如 Trae 的 SOLO 模式才能完整调用技能链普通聊天模式只支持基础能力。确认你是在 SOLO 或 Agent 模式下对话不是普通编辑器聊天窗口。其次是依赖缺失。Skill 里写了调用 Python 脚本、Node 命令或者外部 API但运行环境里没装。就像给厨师一份菜谱厨房里缺盐少锅菜肯定做不出来。检查清单Skill 用到的 CLI 工具装了吗Node 和 Python 版本对吗网络能访问调用的 API 吗文件读写权限够吗。最后是平台差异。不同 Agent 对SKILL.md的支持度确实有差异有的字段在 A 平台是标配到 B 平台就不识别。跨平台开发时建议只用最通用的字段name、description、triggers其他高级特性做降级兼容。7. 本篇常见错排查四步法照着走遇到 Skill 不生效按下面顺序走找到问题就停。第一步验证加载状态。确认目录路径和文件名完全正确检查 YAML 头格式重启客户端或重新加载技能去技能列表里看有没有显示出来。这一步过不了问题在第一层不要往下看。第二步手动强制调用。直接在对话里说“使用 XXX Skill 来处理这个问题”。能正常执行说明是触发层问题回去改description还是没反应回到第一步。第三步对比输出差异。手动调用成功了但输出不对看是不是和全局 Rule 冲突看用户 Prompt 里有没有覆盖性指令关掉其他 Skill 单独测试排除互相干扰。第四步检查运行环境。前三步都没问题但还是报错确认运行模式检查依赖工具是否安装查看日志有没有报错换个平台测试确认是不是兼容性问题。经验数据是大部分问题在第一步就能解决一部分在第二步剩下很少在后两层。排错的黄金法则永远是从最简单的地方查起先确认文件放对了再谈写得好不好先确认 AI 能看见再谈它愿不愿意用。如果你在验证请求是否真正到达模型这一步卡住了可以直接用模型对话页面发一条测试消息确认通道正常https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期做编码和 Agent 的话Coding Plan 会更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Claude Code 相关配置看 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。把通道固定下来再回头查 Skill你会发现大部分“玄学失效”其实都有明确的层级归属。