Copilot CLI: User-level agents not loading from ~/.copilot/agents (GitHub Issue #452)

[rjmurillo]

Summary

GitHub Copilot CLI does not recognize custom agents from the user-level ~/.copilot/agents/ directory, despite documentation stating this location should work. This is a known bug documented in github/copilot-cli#452.

Symptoms

When running copilot --agent my-agent --prompt "test", the CLI responds:

No such agent: my-agent, available:

The "available:" list is empty, indicating no agents were discovered from the user-level directory.

Environment

• Copilot CLI version: 0.0.367+
• Agent files location: ~/.copilot/agents/
• Tested platforms: Windows 11 (may affect all platforms)

Root Cause

The Copilot CLI only loads agents from repository-level .github/agents/ directories and ignores user-level agents in ~/.copilot/agents/, despite documentation stating otherwise.

Workaround

Use repository-level installation instead of global:

1. Create .github/agents/ directory in your repository
2. Place your .agent.md files there
3. Agents will be recognized when running Copilot CLI from that repository

Example:

mkdir -p .github/agents
cp my-agent.agent.md .github/agents/
copilot --agent my-agent --prompt "test"  # Now works!

Impact

• Users cannot share agents globally across all repositories
• Each repository must have its own copy of agents
• The documented behavior for ~/.copilot/agents/ does not work

References

• GitHub Issue #452: User-level custom agents not loading
• Creating custom agents - GitHub Docs
• Custom agents configuration - GitHub Docs

Action Items

• Identified root cause as upstream bug #452
• Documented workaround (repository-level installation)
• Monitor upstream Issue #452 for resolution
• Update documentation once bug is fixed

[groupzer0]

@rjmurillo Thanks for the heads-up on this! I'll update the docs ASAP.

[groupzer0]

Addressed in commit 02355b7. Thanks again for raising this issue.