microsoft / microsoft/vscode

Skills: nested skill directory discovery (organizational subfolders + nested project subdirectories)

Open
#324,646 1 comment 9 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.