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

[roomote]

This PR attempts to address RooCodeInc/Roo-Code#11368. Feedback and guidance are welcome.

Summary

The .agents/skills/ directory support was implemented in Roo Code v3.47.2 (via PR #11181) but the skills documentation only references .roo/skills/ paths. This PR updates the docs to cover the .agents/skills/ paths.

Changes

Updates docs/features/skills.mdx to document:

• .agents/skills/ as an alternative project-level skill location (shared across AI tools)
• ~/.agents/skills/ as an alternative global skill location
• .agents/skills-{mode}/ and ~/.agents/skills-{mode}/ for mode-specific variants
• The full override priority chain (.roo/ takes precedence over .agents/ at the same level)
• A cross-tool compatibility tip explaining when to use .agents/ vs .roo/
• Updated directory structure examples showing both path prefixes side by side

Context

Multiple AI coding tools have adopted the .agents/ convention per the Agent Skills standard. Documenting this helps users who work across tools understand they can share skills without moving files or creating symlinks.

---

Important

Updates docs/features/skills.mdx to document .agents/skills/ paths for cross-tool compatibility and explains their priority over .roo/skills/.

• Documentation Update:
  • Adds .agents/skills/ and ~/.agents/skills/ paths to docs/features/skills.mdx for cross-tool compatibility.
  • Explains override priority: .roo/ paths take precedence over .agents/ paths.
  • Provides examples of directory structures showing both .roo/ and .agents/ paths.
• Cross-Tool Compatibility:
  • Introduces .agents/skills/ paths as per the Agent Skills standard.
  • Includes a tip on when to use .agents/skills/ vs .roo/skills/.
• Mode-Specific Skills:
  • Documents mode-specific variants for both .roo/ and .agents/ paths.

^{This description was created by for 4576b48. You can customize this summary. It will automatically update as commits are pushed.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
roo-code-docs	Ready	Preview, Comment	Feb 10, 2026 9:02am

[roomote]

Rooviewer   See task

The .agents/skills/ documentation additions are well-structured overall, but the override priority section doesn't match the actual SkillsManager implementation. One issue flagged:

• Override priority order is incorrect (lines 220-233): The shouldOverrideSkill() implementation resolves by source level first, then mode-specificity within the same source -- it does not treat .roo/ as universally higher priority than .agents/ at the same source level. A project .agents/ mode-specific skill beats a project .roo/ generic skill. The numbered list and bullet-point summary need to be reordered.

_{Mention @roomote in a comment to request specific changes to this pull request or fix all unresolved issues.}

[roomote]

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.}