Skills: nested skill directory discovery (organizational subfolders + nested project subdirectories)
- Dominant language
- TypeScript
- Stars
- 193k
- Forks
- 42.4k
- PR merge metrics
- PR metrics pending
Description
## Follow-up to #293277 (closed) and #285172
Skills are discovered as `.github/skills//SKILL.md` folders. Today discovery is essentially flat: skills must live directly under a configured skills root (e.g. the workspace-root `.github/skills/`, or paths in `chat.agentSkillsLocations`). Two organizational patterns are not supported and would meaningfully improve how teams structure skills.
### Way 1 — Organizational subdirectories inside a skills root
Allow arbitrary grouping folders inside a skills root, walked recursively. Any `SKILL.md` found underneath is picked up, so skills can be grouped by category, team, or domain:
```
.github/
└── skills/
├── shipping/
│ ├── land-it/
│ │ └── SKILL.md
│ └── careful-merge-conflicts/
│ └── SKILL.md
├── debugging/
│ └── using-datadog-mcp/
│ └── SKILL.md
└── workflow/
└── tdd/
└── SKILL.md
```
The category folder is purely organizational. The skill's identity comes from the folder directly containing `SKILL.md` (`land-it`, `tdd`, …), not the parent category folder.
### Way 2 — Nested project subdirectories (monorepo colocation)
Discover `.github/skills/` folders located *anywhere* inside the repository, not just at the workspace root, so a monorepo can colocate skills with the package they apply to:
```
my-monorepo/
├── .github/skills/ # repo-wide skills
│ └── land-it/SKILL.md
└── apps/
└── web/
└── .github/skills/ # app-specific skills
└── deploy-web/SKILL.md
```
Skills in a nested project directory would be automatically scoped to files inside that directory. In the example, `deploy-web` is only surfaced when working with files under `apps/web/`, while repo-wide skills in the root `.github/skills/` remain available everywhere. This is equivalent to setting a `paths`/scope on the skill — a nested skill wouldn't need explicit scoping to be limited to its directory.
### Additional considerations
- **Performance**: Recursive scanning (especially Way 2) should be cached and driven by file watchers rather than walking the tree on every request. This was the primary concern raised when #293277 was closed.
- **Namespace collisions**: Define precedence rules when skill names collide across scopes (narrower/nested scope wins).
- **Settings integration**: `chat.agentSkillsLocations` could support glob patterns (e.g. `**/.github/skills`) as an opt-in alternative to fully automatic traversal, keeping the performance cost opt-in.
- **Prior art**: Nested/recursive discovery and directory-scoped skills are an emerging convention in the Agent Skills ecosystem; aligning improves portability of skills across tools.
Contributor guide
Research direction
No implementation files or tests are named. Start by tracing discovery from the configured chat.agentSkillsLocations and the .github/skills/SKILL.md convention, then review the concerns from #293277 and #285172. Done means recursive organizational and nested-project discovery, scoping, collision precedence, and watcher-backed performance are defined and implemented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript, vscode
- Domain
- developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100