Add docs for skills

docs/features/index.md

@@ -40,6 +40,7 @@ Discover the powerful features that make Roo Code your ultimate AI-powered codin
 ### Configuration & Customization
 - [**API Configuration Profiles**](/features/api-configuration-profiles) - Manage multiple API configurations
 - [**Custom Instructions**](/features/custom-instructions) - Personalize AI behavior
+- [**Skills**](/features/skills) - Create reusable task-specific instruction packages
 - [**Settings Management**](/features/settings-management) - Fine-tune Roo Code to your preferences
 - [**.rooignore**](/features/rooignore) - Control file access and visibility
 

docs/features/skills.md

@@ -0,0 +1,316 @@
+---
+description: Learn how to create reusable skills that package task-specific instructions, making Roo Code more effective at specialized workflows.
+keywords:
+  - skills
+  - task-specific instructions
+  - agentskills
+  - SKILL.md
+  - reusable instructions
+  - workflow automation
+image: /img/social-share.jpg
+---
+
+# 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`](/advanced-usage/available-tools/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):
+```bash
+# Linux/macOS
+~/.roo/skills/{skill-name}/SKILL.md
+
+# Windows
+%USERPROFILE%\.roo\skills\{skill-name}\SKILL.md
+```
+
+**Project skills** (specific to current workspace):
+```bash
+<project-root>/.roo/skills/{skill-name}/SKILL.md
+```
+
+#### 2. Create the skill directory and file
+
+```bash
+# 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`:
+
+```markdown
+---
+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.
+
+#### Symlink support
+
+Skills support symbolic links for sharing:
+
+```bash
+# 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
+   ```markdown
+   # ✗ 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
+   ```markdown
+   # ✗ 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
+
+| Feature | Skills | Custom Instructions | Slash Commands |
+|---------|--------|---------------------|----------------|
+| **When loaded** | On-demand (when request matches) | Always (part of base prompt) | On-demand (when invoked) |
+| **Best for** | Task-specific workflows | General coding standards | Retrieving pre-written content |
+| **Can bundle files** | Yes | No | No |
+| **Mode targeting** | Yes (`skills-{mode}` directories) | Yes (`rules-{mode}` directories) | No |
+| **Override priority** | Project > Global, Mode > Generic | Project > Global | Project > Global |
+| **Format** | SKILL.md with frontmatter | Any text file | JSON metadata + content |
+| **Discovery** | Automatic (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](https://agentskills.io/) 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
+
+- [Custom Instructions](/features/custom-instructions) - Set general rules that apply to all work
+- [Slash Commands](/features/slash-commands) - Execute commands that return content
+- [Custom Modes](/features/custom-modes) - Create specialized modes with specific tool access

sidebars.ts

@@ -42,6 +42,7 @@ const sidebars: SidebarsConfig = {
            'features/model-temperature',
            'features/concurrent-file-reads',
            'features/rooignore',
+           'features/skills',
            'features/slash-commands',
            'features/suggested-responses',
            'features/task-todo-list',