Skip to main content

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 always knows which skills are available by reading their name and description from frontmatter. This lightweight metadata helps Roo decide which skills match your request.

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 - Roo accesses additional skill files (scripts, templates, references) only as needed during execution.

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/skills/{skill-name}/SKILL.md

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

Project skills (specific to current workspace):

<project-root>/.roo/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

Critical rules:

  • The name field must exactly match the directory name
  • Both name and description are required
  • 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 skills
├── pdf-processing/
│   ├── SKILL.md                 # Required
│   ├── extract.py               # Optional: bundled scripts
│   └── templates/               # Optional: related files
│       └── output-template.md
└── api-docs-generator/
    └── SKILL.md

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

Mode-specific skills​

Create skills that only activate in specific modes:

~/.roo/skills-code/              # Only in Code mode
└── refactoring-patterns/
    └── SKILL.md

.roo/skills-architect/           # Only in Architect mode
└── system-design-templates/
    └── SKILL.md

~/.roo/skills-{modeSlug}/        # Any mode

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:

  1. Project mode-specific (.roo/skills-code/my-skill/)
  2. Global mode-specific (~/.roo/skills-code/my-skill/)
  3. Project generic (.roo/skills/my-skill/)
  4. Global generic (~/.roo/skills/my-skill/)

This lets you:

  • Set global standards that work everywhere
  • Override them per-project when needed
  • Specialize skills for specific modes

Skill Discovery​

Roo automatically discovers skills:

  • At startup: All skills are indexed
  • 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.

Skills support symbolic links for sharing:

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

# Use different names for the same skill
ln -s ~/.roo/skills/pdf-processing ~/.roo/skills/pdf-handler

The skill name comes from the symlink name (or directory name if not symlinked). The frontmatter name field must still match this name.

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

    # ✗ 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

    # ✗ 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​

FeatureSkillsCustom InstructionsSlash Commands
When loadedOn-demand (when request matches)Always (part of base prompt)On-demand (when invoked)
Best forTask-specific workflowsGeneral coding standardsRetrieving pre-written content
Can bundle filesYesNoNo
Mode targetingYes (skills-{mode} directories)Yes (rules-{mode} directories)No
Override priorityProject > Global, Mode > GenericProject > GlobalProject > Global
FormatSKILL.md with frontmatterAny text fileJSON metadata + content
DiscoveryAutomatic (directory scan)Automatic (directory scan)Automatic (directory scan)

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 open standard for skill packaging and metadata. This means skills you create are portable across Agent Skills-compatible tools, including:

  • Roo Code - Available in all modes with automatic discovery
  • GitHub Copilot (VS Code) - Works in chat and coding agent
  • OpenAI Codex - Accessible in CLI and IDE extensions
  • Other compatible agents - Any tool implementing the Agent Skills standard

Roo-specific enhancements​

While maintaining compatibility with the core standard, Roo Code adds mode-specific targeting:

  • Standard locations: .roo/skills/ and ~/.roo/skills/ work with any Agent Skills-compatible tool
  • Mode-specific directories: skills-{mode}/ (e.g., skills-code/, skills-architect/) are Roo enhancements that enable mode targeting without affecting portability—other tools will simply ignore these directories

This means you can:

  • Share generic skills across different AI tools
  • Use mode-specific optimizations when working in Roo Code
  • Maintain a single skill library that works everywhere

See Also​