droid CLI: document personal skill discovery roots and ~/.agents/skills behavior

[coygeek]

This was generated by AI during triage.

Summary

I'm testing with droid (the CLI/TUI version, not the app or IDE integration) on v0.143.0, using fresh tmux sessions.

While investigating why some personal skills were visible and others were not, I found that the droid CLI appears to load top-level ~/.agents/skills/ as personal skills, even though the docs only describe:

• personal skills at ~/.factory/skills/
• repo-local compatibility skills at <repo>/.agent/skills/
• import from .claude/skills

That undocumented behavior made it much harder to diagnose what was actually happening.

What I observed

In fresh tmux sessions running droid:

• the startup banner showed Skills (30)
• the Personal tab in /skills also showed 30 skills
• that count matched the number of direct skill folders in my top-level ~/.agents/skills/
• a skill that exists in ~/.agents/skills/ (setup-matt-pocock-skills) appears in the slash menu

At the same time, I had other skills elsewhere that were not showing up. After tracing the local layout, those missing skills turned out to be a separate local path/layout issue on my side.

So the missing-skill part was my own setup, but the confusing part is still real: droid CLI seems to be loading ~/.agents/skills/ as a personal root even though that path is not documented.

Why this matters

The current docs made me expect that personal skill discovery was coming from ~/.factory/skills/ only. Because ~/.agents/skills/ was also being loaded, it looked like skill discovery was inconsistent or partially broken.

This makes troubleshooting harder because some skills can appear "magically" from an undocumented root while other skills fail to appear for unrelated reasons.

Repro notes

Environment used for testing:

• droid CLI v0.143.0
• tested in fresh tmux sessions
• using the droid CLI/TUI directly

Relevant checks from the investigation:

• top-level ~/.agents/skills/ contained 30 direct skills
• fresh droid sessions showed Skills (30)
• /setup-matt-pocock-skills was discoverable in the slash menu

Request

Could you either:

1. document that ~/.agents/skills/ is a supported personal skill discovery root for the droid CLI, including any precedence rules relative to ~/.factory/skills/,

or

2. if that path is not intended to be supported, stop scanning it (or emit a warning) so the documented behavior matches the actual behavior.

It would also help to explicitly document that personal skills under ~/.factory/skills/ need to be direct children like:

~/.factory/skills/<name>/SKILL.md

rather than nested one extra directory down.