新闻详情

新闻详情

首页 / 资讯中心 / 详情

RooCode Skills 不识别问题解决方案:从 SKILL.md frontmatter 到 VSCode 配置排查

发布时间:2026/11/16 20:51:16来源:尧图网络
RooCode Skills 不识别问题解决方案:从 SKILL.md frontmatter 到 VSCode 配置排查
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 会更合适。
网站建设高端定制企业官网
RELATED

相关资讯

更多精彩内容,欢迎继续阅读

较早相关资讯

最新相关资讯

【外设】之大彩串口显示屏 2026/11/15 4:54:16

【外设】之大彩串口显示屏

大彩串口屏初步使用 1 .官网下载 STM32 屏幕 GUI 设计资料 http://www.gz-dc.com/category/typeid/4112 找到 STM32 Keil 工程,移植相关代码因项目而异进行移植,由于项目简单,本人只对用到的指令接口进行修改。 比如:注意事项&…

阅读更多 →
无法下载Windows系统iso文件 2026/11/15 2:04:12

无法下载Windows系统iso文件

当我遇到这个问题的时候,我打开了一个网站: 登录 然后我打算下载的时候: 突然那个官方的连接就可以下载了:

阅读更多 →
【清华代码熊】DeepSeek V4.1 Flash 后训练详解 2026/11/16 19:23:38

【清华代码熊】DeepSeek V4.1 Flash 后训练详解

📌 上期解析了 DeepSeek V4.1 Flash 模型架构改进,本期解析 DeepSeek V4.1 Flash 预训练/后训练技术: 🌟 预训练:45T 文本 多模态混合语料、直接训练 sparse attention(取消 DeepSeek V4 的 dense 冷启动&…

阅读更多 →
Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ... 2026/11/16 6:47:19

Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ...

文章主要内容和创新点 主要内容 本文聚焦于多模态大语言模型(MLLM)强化学习(RL)训练中的效率问题,提出了一个名为Shuffle-R1的框架。研究发现,当前RL训练存在两个关键缺陷: 优势值坍缩(Advantage Collapsing):批次中大多数优势值集中在零附近,导致有效梯度信号被淹…

阅读更多 →
PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction 2026/11/14 16:35:50

PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction

一、文章主要内容总结 本文聚焦于利用大型语言模型(LLMs)实现个人身份信息(PII)脱敏的研究,旨在解决传统脱敏方法(如基于规则的系统、领域特定命名实体识别(NER)模型)泛化能力差、跨格式/跨语境适应性弱的问题。 研究通过全面评估多种LLM架构(包括密集型LLM(D-LLM…

阅读更多 →
LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model 2026/11/16 17:28:18

LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model

文章主要内容和创新点 主要内容 本文聚焦于二进制图像-文本相关性评估任务(判断图像与文本“相关”或“不相关”),针对该任务中文本格式多样、相关性定义随场景变化等挑战,提出了基于多模态大语言模型(MLLM)的解决方案LLaVA-RE。 模型设计:LLaVA-RE基于LLaVA 1.5架构,…

阅读更多 →

今日资讯

本周资讯

本月资讯

看完文章仍有疑问?

联系尧图顾问,获取一对一建站咨询

立即免费咨询 📞 400-888-8888
📞 ✉