Skip to content

docs: document .agents/skills/ paths for cross-tool compatibility #534

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
roomote wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: document .agents/skills/ paths for cross-tool compatibility #534

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 62 additions & 20 deletions docs/features/skills.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ keywords:
- skills
- task-specific instructions
- agentskills
- .agents/skills
- SKILL.md
- reusable instructions
- workflow automation
Expand Down Expand Up @@ -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

Expand All @@ -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
<project-root>/.roo/skills/{skill-name}/SKILL.md

# Shared across AI tools
<project-root>/.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
Expand Down Expand Up @@ -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
Expand All @@ -155,27 +171,43 @@ 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

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)
Expand All @@ -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
Comment on lines +220 to +233
Copy link
Contributor Author

@roomote roomote bot Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The 8-level priority list and the three bullet points below it don't match the actual shouldOverrideSkill() implementation in SkillsManager.ts. The resolution logic checks source level first (project > global), then mode-specificity within the same source -- it does not distinguish .roo/ from .agents/ during resolution at all. The .roo/ vs .agents/ replacement only happens during discovery when both exist at the same source + mode level (via scan-order in getSkillsDirectories). This means a project .agents/ mode-specific skill actually beats a project .roo/ generic skill, because shouldOverrideSkill sees them as same-source and mode-specific wins. The correct order should be:

Suggested change
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
When skills with the same name exist in multiple locations, this priority applies. The ordering evaluates project vs global first, then mode-specific vs generic within each source, then `.roo/` vs `.agents/` within each source and specificity:
1. **Project `.roo/` mode-specific** (`.roo/skills-code/my-skill/`) — highest priority
2. **Project `.agents/` mode-specific** (`.agents/skills-code/my-skill/`)
3. **Project `.roo/` generic** (`.roo/skills/my-skill/`)
4. **Project `.agents/` generic** (`.agents/skills/my-skill/`)
5. **Global `.roo/` mode-specific** (`~/.roo/skills-code/my-skill/`)
6. **Global `.agents/` mode-specific** (`~/.agents/skills-code/my-skill/`)
7. **Global `.roo/` generic** (`~/.roo/skills/my-skill/`)
8. **Global `.agents/` generic** (`~/.agents/skills/my-skill/`) — lowest priority
This means:
- **Project** always overrides **global** at any prefix
- **Mode-specific** overrides **generic** within the same source level (regardless of prefix)
- **`.roo/`** overrides **`.agents/`** at the same source level and same mode specificity

Fix it with Roo Code or mention @roomote and request a fix.

- **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

---
Expand Down Expand Up @@ -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

---

Expand Down