From 4576b488357ac5e179880b12962eda837999402c Mon Sep 17 00:00:00 2001 From: Roo Code Date: Tue, 10 Feb 2026 09:00:59 +0000 Subject: [PATCH] docs: document .agents/skills/ paths for cross-tool compatibility --- docs/features/skills.mdx | 82 ++++++++++++++++++++++++++++++---------- 1 file changed, 62 insertions(+), 20 deletions(-) diff --git a/docs/features/skills.mdx b/docs/features/skills.mdx index fae11c47..72ec247f 100644 --- a/docs/features/skills.mdx +++ b/docs/features/skills.mdx @@ -4,6 +4,7 @@ keywords: - skills - task-specific instructions - agentskills + - .agents/skills - SKILL.md - reusable instructions - workflow automation @@ -47,9 +48,10 @@ You can't package bundled assets (scripts, templates, references) with custom in - **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 +- **Team Sharing**: Version-control project skills in `.roo/skills/` (or `.agents/skills/`) for consistent team workflows +- **Personal Library**: Build a global skills library in `~/.roo/skills/` (or `~/.agents/skills/`) that works across all projects +- **Cross-Tool Compatibility**: Use `.agents/skills/` paths to share skills with other AI coding tools that support the [Agent Skills](https://agentskills.io/) standard +- **Override Control**: Project skills override global skills, `.roo/` overrides `.agents/`, mode-specific overrides generic ## How Skills Work @@ -71,18 +73,32 @@ This architecture means skills remain dormant until activated—they don't bloat **Global skills** (available in all projects): ```bash -# Linux/macOS +# Roo-specific (Linux/macOS) ~/.roo/skills/{skill-name}/SKILL.md -# Windows +# Roo-specific (Windows) %USERPROFILE%\.roo\skills\{skill-name}\SKILL.md + +# Shared across AI tools (Linux/macOS) +~/.agents/skills/{skill-name}/SKILL.md + +# Shared across AI tools (Windows) +%USERPROFILE%\.agents\skills\{skill-name}\SKILL.md ``` **Project skills** (specific to current workspace): ```bash +# Roo-specific /.roo/skills/{skill-name}/SKILL.md + +# Shared across AI tools +/.agents/skills/{skill-name}/SKILL.md ``` +:::tip Cross-Tool Compatibility +The `.agents/skills/` paths follow the [Agent Skills](https://agentskills.io/) standard and are shared across multiple AI coding tools (e.g., Codex, Copilot). Use `.agents/skills/` when you want skills that work across different tools, and `.roo/skills/` for Roo-specific skills. If a skill with the same name exists in both locations, the `.roo/` version takes priority. +::: + #### 2. Create the skill directory and file ```bash @@ -146,7 +162,7 @@ Roo should recognize the request matches your skill description, load the SKILL. #### Basic structure ``` -~/.roo/skills/ # Global skills +~/.roo/skills/ # Global Roo-specific skills (highest global priority) ├── pdf-processing/ │ ├── SKILL.md # Required │ ├── extract.py # Optional: bundled scripts @@ -155,9 +171,17 @@ Roo should recognize the request matches your skill description, load the SKILL. └── api-docs-generator/ └── SKILL.md -.roo/skills/ # Project skills (override global) +~/.agents/skills/ # Global shared skills (lower priority than ~/.roo) +└── cross-tool-skill/ + └── SKILL.md + +.roo/skills/ # Project Roo-specific skills (override global) └── custom-pdf-workflow/ └── SKILL.md + +.agents/skills/ # Project shared skills (lower priority than .roo) +└── shared-workflow/ + └── SKILL.md ``` #### Mode-specific skills @@ -165,17 +189,25 @@ Roo should recognize the request matches your skill description, load the SKILL. Create skills that only activate in specific modes: ``` -~/.roo/skills-code/ # Only in Code mode +~/.roo/skills-code/ # Only in Code mode (Roo-specific) └── refactoring-patterns/ └── SKILL.md -.roo/skills-architect/ # Only in Architect mode +~/.agents/skills-code/ # Only in Code mode (shared across tools) +└── shared-refactoring/ + └── SKILL.md + +.roo/skills-architect/ # Only in Architect mode (Roo-specific) └── system-design-templates/ └── SKILL.md -~/.roo/skills-{modeSlug}/ # Any mode +.agents/skills-architect/ # Only in Architect mode (shared across tools) +└── shared-design-templates/ + └── SKILL.md ``` +The pattern `skills-{modeSlug}/` works with both `.roo/` and `.agents/` prefixes at both global and project levels. + **When to use mode-specific skills:** - Code refactoring patterns (Code mode only) - System design templates (Architect mode only) @@ -185,18 +217,27 @@ Create skills that only activate in specific modes: ## Override Priority -When skills with the same name exist in multiple locations, this priority applies (project vs global is evaluated first, then mode-specific vs generic within each source): +When skills with the same name exist in multiple locations, this priority applies. The ordering evaluates project vs global first, then `.roo/` vs `.agents/` within each source, then mode-specific vs generic: -1. **Project mode-specific** (`.roo/skills-code/my-skill/`) -2. **Project generic** (`.roo/skills/my-skill/`) -3. **Global mode-specific** (`~/.roo/skills-code/my-skill/`) -4. **Global generic** (`~/.roo/skills/my-skill/`) +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 -This means a **project generic** skill overrides a **global mode-specific** skill—project location takes precedence over mode specificity. +This means: +- **Project** always overrides **global** at any prefix +- **`.roo/`** always overrides **`.agents/`** at the same level +- **Mode-specific** overrides **generic** within the same prefix and level This lets you: +- Share skills across AI tools via `.agents/skills/` +- Override shared skills with Roo-specific versions in `.roo/skills/` - Set global standards that work everywhere -- Override them per-project when needed (even with generic skills) +- Override them per-project when needed - Specialize skills for specific modes within each location --- @@ -322,10 +363,11 @@ Roo Code skills follow the [Agent Skills](https://agentskills.io/) format for sk #### Roo-specific enhancements -Roo Code adds mode-specific targeting beyond the base format: +Roo Code extends the base Agent Skills format with additional features: -- **Standard locations**: `.roo/skills/` and `~/.roo/skills/` -- **Mode-specific directories**: `skills-{mode}/` (e.g., `skills-code/`, `skills-architect/`) enable mode targeting +- **Roo-specific locations**: `.roo/skills/` and `~/.roo/skills/` (take priority over `.agents/` equivalents) +- **Shared locations**: `.agents/skills/` and `~/.agents/skills/` (compatible with other AI coding tools) +- **Mode-specific directories**: `skills-{mode}/` (e.g., `skills-code/`, `skills-architect/`) enable mode targeting in both `.roo/` and `.agents/` paths ---