Skills

Skills 将特定任务的指令打包，当你的请求与技能用途匹配时，Roo 会按需加载这些指令。与适用于所有场景的自定义指令不同，skills 仅在需要时激活——使 Roo 在专业任务中更加高效，同时避免干扰基础提示。

---

为什么重要

自定义指令广泛适用于你所有的任务。它们非常适合通用编码标准或风格偏好，但对于“处理 PDF 文件”或“生成 API 文档”等特定工作流程则不够理想。

Skills 解决了这个问题：为 PDF 处理创建一个 skill，Roo 只会在你实际要求处理 PDF 时加载这些指令。这能保持系统提示的专注性，并让 Roo 在特定领域具备深入的专业知识，而不会影响无关任务。

你无法将捆绑资源（脚本、模板、参考资料）与自定义指令一起打包。Skills 允许你将相关文件与指令一起存储，创建自包含的工作流包。

Skills 能让你做什么

• 任务特定专业知识：为专业工作流程打包详细指令（数据处理、文档生成、代码迁移模式）
• 捆绑资源：在指令旁包含辅助脚本、模板或参考文件
• 模式定向：创建仅在特定模式下激活的 skills（例如，代码重构 skills 仅在 Code 模式下激活）
• 团队共享：在 .roo/skills/ 中对项目 skills 进行版本控制，实现一致的工作流程
• 个人库：在 ~/.roo/skills/ 中构建全局 skills 库，适用于所有项目
• 覆盖控制：项目 skills 覆盖全局 skills，模式特定的覆盖通用的

Skills 如何工作

Skills 使用渐进式披露来高效地仅在需要时加载内容：

级别 1：发现 - Roo 读取每个 SKILL.md 文件并解析其 frontmatter 以提取 name 和 description。只存储此元数据用于匹配——完整内容不会保存在内存中，直到需要时。

级别 2：指令 - 当你的请求与 skill 的描述匹配时，Roo 使用 read_file 将完整的 SKILL.md 指令加载到上下文中。

级别 3：资源 - 提示告诉 Roo 它可以访问与 skill 捆绑的文件（脚本、模板、参考资料）。没有单独的资源清单——当指令引用这些文件时，Roo 会按需发现它们。

这种架构意味着 skills 在激活前保持休眠状态——它们不会使你的基础提示臃肿。你可以安装许多 skills，Roo 只为每个任务加载相关的内容。

---

创建你的第一个 Skill

1. 选择位置

全局 skills（在所有项目中可用）：

# Linux/macOS
~/.roo/skills/{skill-name}/SKILL.md

# Windows
%USERPROFILE%\.roo\skills\{skill-name}\SKILL.md

项目 skills（特定于当前工作空间）：

<project-root>/.roo/skills/{skill-name}/SKILL.md

2. 创建 skill 目录和文件

# 示例：PDF 处理 skill
mkdir -p ~/.roo/skills/pdf-processing
touch ~/.roo/skills/pdf-processing/SKILL.md

3. 编写 SKILL.md 文件

文件需要包含带有 name 和 description 的 frontmatter：

---
name: pdf-processing
description: 使用 Python 库从 PDF 文件中提取文本和表格
---

# PDF 处理指令

当用户请求 PDF 处理时：

1. 检查是否安装了 PyPDF2 或 pdfplumber
2. 对于文本提取，使用 pdfplumber 以获得更好的表格检测
3. 对于简单的纯文本 PDF，PyPDF2 就足够了
4. 始终优雅地处理编码错误
5. 提供将提取的内容保存到文件的选项

## 代码模板

[在此处放置你的详细代码模式]

## 常见问题

- 加密 PDF：说明它们需要密码参数
- 扫描 PDF：推荐使用 OCR 工具如 pytesseract
- 大文件：建议逐页处理

命名规则：

• name 字段必须与目录名（或符号链接名）完全匹配
• 名称必须为 1-64 个字符，只能包含小写字母/数字/连字符
• 不能有前导/尾随连字符，不能有连续连字符（例如，my--skill 无效）
• name 和 description 都是必需的
• 描述必须为 1-1024 个字符（会被修剪）
• 描述告诉 Roo 何时使用此 skill——要具体

4. 测试 skill

向 Roo 提出与描述匹配的问题：

"你能帮我从这个 PDF 文件中提取表格吗？"

Roo 应该识别请求与你的 skill 描述匹配，加载 SKILL.md 文件，并遵循其指令。

---

目录结构

基本结构

~/.roo/skills/                    # 全局 skills
├── pdf-processing/
│   ├── SKILL.md                 # 必需
│   ├── extract.py               # 可选：捆绑脚本
│   └── templates/               # 可选：相关文件
│       └── output-template.md
└── api-docs-generator/
    └── SKILL.md

.roo/skills/                      # 项目 skills（覆盖全局）
└── custom-pdf-workflow/
    └── SKILL.md

模式特定 skills

创建仅在特定模式下激活的 skills：

~/.roo/skills-code/              # 仅在 Code 模式下
└── refactoring-patterns/
    └── SKILL.md

.roo/skills-architect/           # 仅在 Architect 模式下
└── system-design-templates/
    └── SKILL.md

~/.roo/skills-{modeSlug}/        # 任何模式

何时使用模式特定 skills：

• 代码重构模式（仅在 Code 模式下）
• 系统设计模板（仅在 Architect 模式下）
• 文档标准（特定于文档编写模式）

---

覆盖优先级

当相同名称的 skills 存在于多个位置时，应用此优先级（先评估项目与全局，然后在每个源内评估模式特定与通用）：

1. 项目模式特定 (.roo/skills-code/my-skill/)
2. 项目通用 (.roo/skills/my-skill/)
3. 全局模式特定 (~/.roo/skills-code/my-skill/)
4. 全局通用 (~/.roo/skills/my-skill/)

这意味着项目通用 skill 会覆盖全局模式特定 skill——项目位置优先于模式特定性。

这让你能够：

• 设置适用于所有位置的全局标准
• 按项目需要覆盖它们（即使是使用通用 skills）
• 在每个位置内为特定模式专门化 skills

---

Skill 发现

Roo 自动发现 skills：

• 启动时：通过读取和解析每个 SKILL.md 来索引所有 skills
• 开发过程中：文件监视器检测 SKILL.md 文件的更改
• 模式过滤：只有与当前模式相关的 skills 才可用

你不需要注册或配置 skills——只需创建目录结构。

自定义系统提示会覆盖 Skills

如果你有基于文件的自定义系统提示 (.roo/system-prompt-{mode-slug})，它会完全替换标准系统提示——包括 skills 部分。当自定义系统提示激活时，skills 将不可用。

符号链接支持

Skills 支持符号链接，用于在项目间共享 skill 库：

# 在项目间共享 skill 库
ln -s /shared/company-skills ~/.roo/skills/company-standards

技能名称来源于符号链接名称（如果没有符号链接，则为目录名称）。frontmatter 中的 name 字段必须与此名称完全匹配——您不能使用不同的名称创建指向同一技能的别名。

---

故障排除

技能未加载

症状：即使您请求的内容与技能描述匹配，Roo 也不会使用您的技能。

原因与修复：

1. 名称不匹配：frontmatter 中的 name 字段必须与目录名称完全匹配

   # ✗ 错误 - 目录名称为 "pdf-processing"
   ---
   name: pdf_processing
   ---
   
   # ✓ 正确
   ---
   name: pdf-processing
   ---

2. 缺少必需字段：frontmatter 中必须包含 name 和 description 字段

3. 模式错误：如果技能位于 skills-code/ 目录中，但您处于 Architect 模式，它将不会加载。请将其移至 skills/ 目录（适用于所有模式）或创建特定于模式的变体。

4. 描述过于模糊：请使描述具体化，以便 Roo 能够将其与请求匹配

   # ✗ 模糊
   description: Handle files
   
   # ✓ 具体
   description: Extract text and tables from PDF files using Python libraries

技能已加载但无帮助

症状：Roo 读取了技能，但没有遵循指示。

原因：指示可能过于笼统或缺少关键细节。

修复：使指示具有可操作性：

• 包含具体的函数名称或库选择
• 提供代码模板
• 列出常见的边缘情况及其处理方法
• 为特定任务添加故障排除指南

多个技能冲突

症状：当多个技能可能匹配时，不清楚 Roo 将使用哪个技能。

原因：描述重叠或模式配置冲突。

预防：

• 使描述具有区分度且具体
• 使用特定于模式的目录来分离关注点
• 依赖覆盖优先级——项目技能覆盖全局技能

无法与团队共享技能

症状：希望团队成员使用相同的技能。

解决方案：将技能放置在项目内的 .roo/skills/ 目录中，并将其提交到版本控制。每个团队成员将自动获得相同的技能。

---

技能 vs 自定义指令 vs 斜杠命令

特性	Skills	Custom Instructions	Slash Commands
加载时机	按需（当请求匹配时）	始终（作为基础提示的一部分）	按需（当被调用时）
最适合	特定任务的工作流	通用编码标准	检索预编写的内容
能否捆绑文件	是	否	否
模式定向	是（skills-{mode} 目录）	是（rules-{mode} 目录）	否
覆盖优先级	项目 > 全局，模式 > 通用	项目 > 全局	项目 > 全局
格式	带有 frontmatter 的 SKILL.md	任何文本文件	JSON 元数据 + 内容
发现方式	自动（目录扫描）	自动（目录扫描）	自动（目录扫描）

何时使用每种方式：

• Skills："Generate API docs following OpenAPI spec" → 仅在需要时加载详细的 OpenAPI 处理说明
• Custom Instructions："Always use TypeScript strict mode" → 适用于所有 TypeScript 工作
• Slash Commands：/init → 返回标准化的项目设置说明

---

技能规范

Roo Code 技能遵循 Agent Skills 格式进行技能打包和元数据管理。技能是带有可选捆绑文件的指令包——它们不会注册新的可执行工具。

必需约定：

• frontmatter 中的 name 必须与目录（或符号链接）名称完全匹配
• frontmatter 中必须包含 name 和 description 字段
• 名称：1–64 个字符，小写字母数字 + 连字符，不能有开头/结尾/连续的连字符
• 描述：1–1024 个字符（自动修剪）

Roo 特定增强功能

Roo Code 在基础格式之外增加了特定于模式的定向功能：

• 标准位置：.roo/skills/ 和 ~/.roo/skills/
• 特定于模式的目录：skills-{mode}/（例如 skills-code/、skills-architect/）启用模式定向

---

另见

• Custom Instructions - 设置适用于所有工作的通用规则
• Slash Commands - 执行返回内容的命令
• Custom Modes - 创建具有特定工具访问权限的专用模式