github / github/copilot-cli

Add `.agents` discovery for instructions, agents, and hooks in any opened folder

Open
#4,204 2 comments 0 reactions 0 assignees View on GitHub
area:agents area:configuration
Dominant language
Shell
Stars
11.2k
Forks
1.9k
Avg merge
14h 16m
Merged PRs (30d)
6

Description

### Describe the feature or problem you'd like to solve
Copilot CLI already uses `.agents/skills`; please extend the same `.agents` convention to instructions, agents, and hooks in any opened folder, not just Git repos.

### Proposed solution
This would let users standardize Copilot customizations under one root, `.agents/`, for any opened workspace/folder, whether or not it is a Git repository, instead of splitting them across `.github/`, `.claude/`, and `~/.copilot/`.

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

Requested default discovery additions:
- `/.agents/instructions/**/*.instructions.md`
- `/.agents/agents/*.agent.md` or the equivalent agent-file convention already used by the product
- `/.agents/hooks/**/*.json` (or the equivalent hook-file convention already used by the product)
- `~/.agents/instructions/**/*.instructions.md`
- `~/.agents/agents/*.agent.md` or the equivalent agent-file convention already used by the product
- `~/.agents/hooks/**/*.json` (or the equivalent hook-file convention already used by the product)

Note: `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` already allows additional instruction directories today; this request is to make `.agents/instructions` a zero-config default. If user-level custom agents or hooks are not already supported, those would be new capability, but the request is still to make `.agents` the canonical root.

Behavioral expectations:
- Works for any opened folder/workspace, including folders that are not Git repositories
- Works consistently with `COPILOT_HOME`
- Discovery is documented and deterministic
- No silent partial loading for a path family
- `/help` and docs reflect the exact supported `.agents` locations

### Example prompts or workflows
1. "Load the repo's coding rules from `.agents/instructions` automatically."
2. "Use the release-notes agent from `.agents/agents`."
3. "Run the startup hook from `.agents/hooks` when I open a plain folder like D:\work\MyProjectOutsideGit."
4. "Keep my user-level instruction files under `~/.agents/` instead of splitting them across `.copilot/` and `.github/`."

### Additional context
Related but distinct: github/copilot-cli#2504 (cwd vs. git-root discovery within Git repos) and github/copilot-cli#1506 (configurable agents folder support). This request is about zero-config `.agents` defaults for any opened folder, Git or not.
This is additive parity, not a migration away from `.copilot` or `.github`.
If it is easier to triage, this could be split into separate issues for instructions / agents / hooks.

Contributor guide

Open the contributing guide

Research direction

Start by tracing the existing .agents/skills discovery and the current instruction, agent, and hook loaders, including COPILOT_HOME handling and /help output. Verify discovery for plain folders and user-level paths, then document the exact supported locations and deterministic behavior without partial loading across a path family.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, shell
Domain
cli, developer-experience
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.