Skills

Skills package task-specific instructions that Roo loads on-demand when your request matches the skill's purpose. Unlike custom instructions that apply to everything, skills activate only when needed—making Roo more effective at specialized tasks without cluttering the base prompt.

Why It Matters

Custom Instructions apply broadly across all your work. They're great for general coding standards or style preferences, but not ideal for specific workflows like "process PDF files" or "generate API documentation."

Skills solve this: Create a skill for PDF processing, and Roo only loads those instructions when you actually ask to work with PDFs. This keeps the system prompt focused and gives Roo deep expertise in specific domains without affecting unrelated tasks.

You can't package bundled assets (scripts, templates, references) with custom instructions. Skills let you store related files alongside the instructions, creating self-contained workflow packages.

What Skills Let You Do

• Task-Specific Expertise: Package detailed instructions for specialized workflows (data processing, documentation generation, code migration patterns)
• Bundled Resources: Include helper scripts, templates, or reference files alongside instructions
• Mode Targeting: Create skills that only activate in specific modes (e.g., code refactoring skills only in Code mode)
• Team Sharing: Version-control project skills in .roo/skills/ for consistent team workflows
• Personal Library: Build a global skills library in ~/.roo/skills/ that works across all projects
• Override Control: Project skills override global skills, mode-specific override generic

How Skills Work

Skills use progressive disclosure to efficiently load content only when needed:

Level 1: Discovery - Roo reads each SKILL.md file and parses its frontmatter to extract name and description. Only this metadata is stored for matching—the full content isn't held in memory until needed.

Level 2: Instructions - When your request matches a skill's description, Roo uses read_file to load the full SKILL.md instructions into context.

Level 3: Resources - The prompt tells Roo it may access bundled files (scripts, templates, references) alongside the skill. There's no separate resource manifest—Roo discovers these files on-demand when the instructions reference them.

This architecture means skills remain dormant until activated—they don't bloat your base prompt. You can install many skills, and Roo loads only what's relevant for each task.

Creating Your First Skill

1. Choose a location

Global skills (available in all projects):

# Linux/macOS — Roo-specific (higher priority)
~/.roo/skills/{skill-name}/SKILL.md

# Linux/macOS — cross-agent (shared with other agent tools)
~/.agents/skills/{skill-name}/SKILL.md

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

Project skills (specific to current workspace):

# Roo-specific (higher priority)
<project-root>/.roo/skills/{skill-name}/SKILL.md

# Cross-agent (shared with other agent tools)
<project-root>/.agents/skills/{skill-name}/SKILL.md

2. Create the skill directory and file

# Example: PDF processing skill
mkdir -p ~/.roo/skills/pdf-processing
touch ~/.roo/skills/pdf-processing/SKILL.md

3. Write the SKILL.md file

The file requires frontmatter with name and description:

---
name: pdf-processing
description: Extract text and tables from PDF files using Python libraries
---

# PDF Processing Instructions

When the user requests PDF processing:

1. Check if PyPDF2 or pdfplumber is installed
2. For text extraction, use pdfplumber for better table detection
3. For simple text-only PDFs, PyPDF2 is sufficient
4. Always handle encoding errors gracefully
5. Offer to save extracted content to a file

## Code Template

[Your detailed code patterns here]

## Common Issues

- Encrypted PDFs: Explain they require password parameter
- Scanned PDFs: Recommend OCR tools like pytesseract
- Large files: Suggest page-by-page processing

Naming rules:

• The name field must exactly match the directory name (or symlink name)
• Names must be 1–64 characters, lowercase letters/numbers/hyphens only
• No leading/trailing hyphens, no consecutive hyphens (e.g., my--skill is invalid)
• Both name and description are required
• Descriptions must be 1–1024 characters (trimmed)
• The description tells Roo when to use this skill—be specific

4. Test the skill

Ask Roo something matching the description:

"Can you help me extract tables from this PDF file?"

Roo should recognize the request matches your skill description, load the SKILL.md file, and follow its instructions.

Directory Structure

Basic structure

~/.roo/skills/                    # Global Roo-specific skills (high priority)
├── pdf-processing/
│   ├── SKILL.md                 # Required
│   ├── extract.py               # Optional: bundled scripts
│   └── templates/               # Optional: related files
│       └── output-template.md
└── api-docs-generator/
    └── SKILL.md

~/.agents/skills/                 # Global cross-agent skills (shared with other agent tools)
└── shared-workflow/
    └── SKILL.md

.roo/skills/                      # Project Roo-specific skills (override global)
└── custom-pdf-workflow/
    └── SKILL.md

.agents/skills/                   # Project cross-agent skills (shared with other agent tools)
└── team-shared-skill/
    └── SKILL.md

Mode-specific skills

Create skills that only activate in specific modes:

~/.roo/skills-code/              # Only in Code mode (Roo-specific, global)
└── refactoring-patterns/
    └── SKILL.md

.roo/skills-architect/           # Only in Architect mode (Roo-specific, project)
└── system-design-templates/
    └── SKILL.md

~/.agents/skills-code/           # Only in Code mode (cross-agent, global)
└── shared-code-skill/
    └── SKILL.md

.agents/skills-{modeSlug}/       # Mode-specific, cross-agent, project

When to use mode-specific skills:

• Code refactoring patterns (Code mode only)
• System design templates (Architect mode only)
• Documentation standards (specific to a doc writing mode)

Override Priority

When skills with the same name exist in multiple locations, this priority applies (highest to lowest). .roo/ paths always take precedence over .agents/ paths at the same project level:

1. Project .roo mode-specific (.roo/skills-code/my-skill/) — highest priority
2. Project .roo generic (.roo/skills/my-skill/)
3. Project .agents mode-specific (.agents/skills-code/my-skill/)
4. Project .agents generic (.agents/skills/my-skill/)
5. Global .roo mode-specific (~/.roo/skills-code/my-skill/)
6. Global .roo generic (~/.roo/skills/my-skill/)
7. Global .agents mode-specific (~/.agents/skills-code/my-skill/)
8. Global .agents generic (~/.agents/skills/my-skill/) — lowest priority

A project skill always overrides a global skill of the same name. Within the same project level, .roo/ overrides .agents/.

This lets you:

• Set global standards that work everywhere
• Override them per-project when needed (even with generic skills)
• Specialize skills for specific modes within each location

Skill Discovery

Roo automatically discovers skills:

• At startup: All skills are indexed by reading and parsing each SKILL.md
• During development: File watchers detect changes to SKILL.md files
• Mode filtering: Only skills relevant to the current mode are available

You don't need to register or configure skills—just create the directory structure.

Symlink support

Skills support symbolic links for sharing skill libraries across projects:

# Share a skill library across projects
ln -s /shared/company-skills ~/.roo/skills/company-standards

The skill name comes from the symlink name (or directory name if not symlinked). The frontmatter name field must match this name exactly—you can't create aliases with different names pointing to the same skill.

Troubleshooting

Skill isn't loading

Symptom: Roo doesn't use your skill even when you request something matching the description.

Causes & fixes:

1. Name mismatch: The frontmatter name field must exactly match the directory name

   markdownCopy

   # ✗ Wrong - directory is "pdf-processing"
   ---
   name: pdf_processing
   ---
   
   # ✓ Correct
   ---
   name: pdf-processing
   ---
   

2. Missing required fields: Both name and description are required in frontmatter

3. Wrong mode: If the skill is in skills-code/ but you're in Architect mode, it won't load. Move to skills/ for all modes or create mode-specific variants.

4. Description too vague: Make descriptions specific so Roo can match them to requests

   markdownCopy

   # ✗ Vague
   description: Handle files
   
   # ✓ Specific
   description: Extract text and tables from PDF files using Python libraries
   

Skill loads but doesn't help

Symptom: Roo reads the skill but doesn't follow instructions.

Cause: Instructions may be too general or missing critical details.

Fix: Make instructions actionable:

• Include specific function names or library choices
• Provide code templates
• List common edge cases and how to handle them
• Add troubleshooting guidance for the specific task

Multiple skills conflict

Symptom: Unclear which skill Roo will use when multiple might match.

Cause: Overlapping descriptions or mode configurations.

Prevention:

• Make descriptions distinct and specific
• Use mode-specific directories to separate concerns
• Rely on override priority—project skills override global

Can't share skills with team

Symptom: Want team members to use the same skills.

Solution: Place skills in .roo/skills/ within your project and commit to version control. Each team member gets the same skills automatically.

Skills vs Custom Instructions vs Slash Commands

When to use each:

• Skills: "Generate API docs following OpenAPI spec" → Detailed OpenAPI processing instructions load only when needed
• Custom Instructions: "Always use TypeScript strict mode" → Applies to all TypeScript work
• Slash Commands: /init → Returns standardized project setup instructions

Skill Specification

Roo Code skills follow the Agent Skills format for skill packaging and metadata. Skills are instruction packages with optional bundled files—they don't register new executable tools.

Required conventions:

• The frontmatter name must exactly match the directory (or symlink) name
• Both name and description fields are required in frontmatter
• Names: 1–64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens
• Descriptions: 1–1024 chars (trimmed)

Roo-specific enhancements

Roo Code adds mode-specific targeting and cross-agent compatibility beyond the base format:

• Roo-specific locations: .roo/skills/, ~/.roo/skills/ (higher priority)
• Cross-agent locations: .agents/skills/, ~/.agents/skills/ (shared with other agent tools)
• Mode-specific directories: skills-{mode}/ (e.g., skills-code/, skills-architect/) in both .roo/ and .agents/ paths enable mode targeting

See Also

• Custom Instructions - Set general rules that apply to all work
• Slash Commands - Execute commands that return content
• Custom Modes - Create specialized modes with specific tool access