microsoft / microsoft/vscode

Extend `.agents` discovery to instructions, agents, and hooks for any opened folder

Open
#326,789 0 comments 0 reactions 1 assignee Claimed by @pwang347 View on GitHub
Dominant language
TypeScript
Stars
193k
Forks
42.4k
PR merge metrics
PR metrics pending

Description

## Feature
Please extend .agents as a first-class customization root for Copilot in VS Code, both for workspace folders and for user-level storage, even when the opened folder is not a Git repository.

This request is specifically about the `.agents/` directory tree, not the root `AGENTS.md` file.

## Current state
Related to the open tracking issue microsoft/vscode#292410, whose checklist already includes "Support other primitives (agents, hooks, instructions/rules, plugins) in `.agents` folder." This issue proposes a concrete, scoped design for that checklist item, plus the additional non-Git-folder guarantee. See also microsoft/vscode#322506 for the related agent-host/session-discovery configurability angle.
- Skills already support `.agents/skills` and `~/.agents/skills`.
- Custom instructions currently cover `.github/copilot-instructions.md`, `*.instructions.md`, root `AGENTS.md`, and the `.claude/.copilot` instruction locations documented today, but not `.agents/instructions`.
- Custom agents currently use `.github/agents`, `.claude/agents`, and `~/.copilot/agents` by default; note that microsoft/vscode#322506 indicates the agent-host/session-discovery layer already hardcodes `.agents/agents` and `.agents/skills` as workspace-level search roots on the SDK/session side, so this request is to make `.agents` an official, documented default consistently across both surfaces, not just a configurable or partially hardcoded one.
- Hooks are Preview. Default locations already include `.github/hooks` and the existing hook settings locations; `.agents/hooks` is not among them.

## Proposed behavior
- Add `.agents/instructions/**/*.instructions.md` and `~/.agents/instructions/**/*.instructions.md` as discovered locations.
- Add `.agents/agents/` and `~/.agents/agents/` to the default agent-location set.
- Once hooks are stable enough for a default-path change, add `.agents/hooks/` and `~/.agents/hooks/` alongside the existing hook locations.
- Discovery should work for any opened workspace folder, including non-Git folders.

Note: `.agents/instructions`, `.agents/agents`, and `.agents/hooks` can already be added manually today via `chat.instructionsFilesLocations`, `chat.agentFilesLocations`, and `chat.hookFilesLocations`. This request is to add them to the default sets, not to add net-new capability.

## What a good solution would let me verify
- Opening a non-Git folder containing `.agents` (for example, `D:\work\MyProjectOutsideGit`) yields the same discovery behavior as a Git-backed folder.
- A workspace containing only `.agents/instructions`, `.agents/agents`, and (when hooks are no longer Preview) `.agents/hooks` behaves consistently without requiring `.github` / `.copilot` equivalents.
- Documented, deterministic handling for same-named files across same-scope roots where applicable.
- Existing `.github` / `.claude` / `.copilot` paths continue to work.

## Why this helps
- One portable customization root across VS Code and Copilot CLI.
- Less duplication across `.github`, `.claude`, and `.copilot`.
- Better fit for teams that standardize on `.agents` in plain folders and monorepos, not only Git repos.

## Related context
Skills already establish the `.agents/` precedent; this request is to close the gap for instructions, agents, and hooks. If needed, this can be split into separate issues per artifact type.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.