1. RooCode Skills 不识别到底卡在哪一步RooCode 是 VSCode 里一个能挂载自定义 Skills 的编码助手插件Skills 可以理解成给模型预置的「技能说明书」——你把某个领域的操作流程、触发条件写进 SKILL.md模型在合适的时候就会自动调用它。适合谁适合已经在用 RooCode 做日常编码、想把自己的重复流程沉淀成可复用技能的人。但很多人第一次加自定义 Skill 就会撞墙目录丢进去了重启 VSCode、重载窗口全局技能区里还是只有 docx、pdf、pptx、skill-creator 那四个自带的自己写的死活不出现。这个问题最难受的地方在于它静默失败。RooCode 扫描 Skill 时只要 frontmatter 有一条校验不过就直接return不弹窗、不警告、列表里也没有。你以为是插件没刷新其实是它压根没把你的目录当成合法 Skill。我试过把同一个 Skill 反复删了重建三次最后才发现是 description 里一个单引号惹的祸。所以这篇不聊虚的直接把 RooCode 的扫描路径、frontmatter 硬性校验规则、VSCode 工作区配置逐项拆开给你一份能直接复制的 SKILL.md 骨架再配上开发者工具里看报错的方法。照着排查基本能定位到根因。2. 先搞清楚 RooCode 扫描 Skill 的路径和校验逻辑在动手改文件之前得先知道插件到底去哪些地方找 Skill。RooCode 会扫描四个位置优先级和用途不同路径作用范围说明~/.roo/skills/全局所有工作区都能用最常用~/.agents/skills/全局备用全局路径workspace/.roo/skills/当前工作区只对打开的这个项目生效workspace/.agents/skills/当前工作区工作区备用路径对每个路径插件会列出子目录然后在每个子目录里找SKILL.md用 gray-matter 解析 frontmatter再做一串校验。核心校验逻辑大致是这样// name 必须存在且是字符串 if (!u.name || typeof u.name ! string) return; // description 必须存在且是字符串 if (!u.description || typeof u.description ! string) return; // name 必须和目录名完全一致 if (u.name ! directoryName) return; // name 只能小写字母、数字、连字符最长 64 if (!/^[a-z0-9](?:-[a-z0-9])*$/.test(name)) return; // description 长度 1–1024 if (description.length 1 || description.length 1024) return;注意这里有两个容易忽略的点一是目录名本身也要满足 name 的格式规则因为校验用的是目录名去比对二是任何一步失败都直接 return没有日志提示。这就是为什么你的 Skill 会「凭空消失」。3. 可复制的 SKILL.md 骨架与目录结构先给一份对照官方已识别技能比如 docx写出来的标准骨架直接抄改就行--- name: my-skill-name description: 一句话说清楚这个 skill 做什么、什么时候触发。如果描述里有单引号就用双引号包住。长度控制在 1024 字符以内。 license: Proprietary. LICENSE.txt has complete terms --- # My Skill Name ## 触发条件 当用户提到 xxx 时使用本技能。 ## 操作步骤 1. 第一步…… 2. 第二步……目录结构必须是这样SKILL.md直接放在以 name 命名的子目录下~/.roo/skills/ └── my-skill-name/ └── SKILL.md几条硬规则再强调一遍name 只能含小写字母、数字、连字符长度不超过 64name 必须和技能目录名一个字母都不能差包括大小写description 长度 1–1024 字符描述里出现单引号时整个值用双引号包起来。注意YAML 里裸字符串包含单引号会让 gray-matter 解析异常description 拿不到正确值Skill 就被过滤掉了。这是最高频的坑。4. VSCode 工作区配置与 settings.json 关键字段如果你把 Skill 放在工作区级别workspace/.roo/skills/要确认 VSCode 打开的是正确的文件夹根目录。RooCode 读取的是当前工作区的根路径如果你打开的是子目录工作区级 Skill 就找不到。工作区配置里跟 Skill 加载相关的字段主要在.vscode/settings.json可以显式声明{ roo.skills.enabled: true, roo.skills.paths: [ ~/.roo/skills, ~/.agents/skills, .roo/skills, .agents/skills ] }如果你用的是多根工作区multi-root workspace每个根目录下的.roo/skills/都会被独立扫描别把 Skill 放错根。另外Windows 上如果用了 junction 或 symlink 把技能目录链接到~/.roo/skills/链接目标改名后一定要同步更新链接否则插件扫到的是失效路径。# 先改成中间名绕过 Windows 大小写重命名限制 Rename-Item my-Skill-Main my-skill-main-tmp Rename-Item my-skill-main-tmp my-skill-main # 更新 junction 指向 rmdir C:\Users\你的用户名\.roo\skills\my-Skill-Main mklink /J C:\Users\你的用户名\.roo\skills\my-skill-main 技能实际所在目录\my-skill-main5. 验证 Skill 是否被正确加载改完文件后别急着重启整个 VSCode先重载窗口CtrlShiftP输入Developer: Reload Window。然后打开开发者工具看日志——这是排查的关键入口。帮助 → 切换开发者工具Help → Toggle Developer Tools切到 Console 标签搜索Skill能看到类似这样的报错Skill name my-skill doesnt match directory my-skill-folder Skill another-skill has an invalid description length: must be 1-1024 characters (got 1050)如果 Console 里干干净净没有任何 Skill 相关输出说明你的目录压根没被扫描到回去检查路径拼写和目录层级。如果能看到 Skill 出现在全局技能区列表里说明加载成功。想进一步验证模型能不能正确调用可以在 RooCode 的对话里直接问它当前有哪些可用技能或者触发你写的触发条件看它是否响应。这一步能确认 frontmatter 里的 description 是否被正确解析。6. 本篇常见错误逐项排查按顺序过一遍基本能覆盖 90% 的「不识别」场景目录名含大写字母。这是最隐蔽的坑。目录叫my-Skill-MainSKILL.md 里写name: my-skill-main看起来 name 格式没问题但校验时用的是目录名去比对目录名本身不合法第一关就挂了。Windows 上重命名大小写要用中间名绕一步上面给了命令。name 和目录名对不上。目录my-skill-folderfrontmatter 写name: my-skill直接跳过。改哪边都行保持一致是关键。description 超长。超过 1024 字符会被静默丢弃这个限制文档里没明说是看源码才发现的。写描述时精炼一点说清触发条件和能力即可别把所有细节塞进 frontmatter。description 含单引号没加引号。裸字符串里的单引号会让 YAML 解析出问题用双引号把整个值包起来就好。YAML 本身格式错误。缩进用了 Tab、冒号后没空格、多行字符串没处理好都会让 gray-matter 解析失败。拿不准就把 frontmatter 贴到在线 YAML 解析器验一下。Skill 放错路径。全局 Skill 必须在~/.roo/skills/或~/.agents/skills/下工作区 Skill 必须在工作区根目录的.roo/skills/下。放错层级插件扫不到。junction/symlink 失效。Windows 上链接目标改名后链接没更新插件扫到的是死路径自然加载不出来。排查时养成先看开发者工具 Console 的习惯比盲目删了重建高效得多。如果 Console 里有明确的 name 不匹配或长度报错直接按提示改如果什么都没有就回到路径和目录名上找问题。Skill 加载通了之后接下来就是让模型真正用起来。如果你还没配好 RooCode 的模型接入可以先去 TaoToken API Keys 拿一个 Key接入文档在 TaoToken 接入文档 里有完整的配置说明。想先验证模型对话是否正常用 模型对话 快速试一下。长期跑编码和 Agent 任务的话Coding Plan 会更合适。
