User-level custom agents not loading from `~/.copilot/agents`

[pietrobondioli]

Describe the bug

Expected Behavior

According to the v0.0.353 release notes, agent definitions should be loaded from both:

• User-level: ~/.copilot/agents
• Repository-level: .github/agents

Actual Behavior

The CLI only loads repository-level agents from .github/agents and ignores user-level agents in ~/.copilot/agents.

Affected version

0.0.353 Commit: f8fd3e3

Steps to reproduce the behavior

Steps to Reproduce

Setup: I have custom agents correctly defined in ~/.copilot/agents and some other agents defined at repository .github/agents folder:

Test 1: No remote setup, but .github/agents exists locally

• Command: copilot
• Command inside copilot: /agents
• User-level agents: Not loaded
• Repo-level agents: Loaded, but with warning message "no github.com remote found"

Test 2: Remote configured with .github/agents folder, but no .github/agents folder locally

• Command: copilot
• Command inside copilot: /agents
• User-level agents: Still not loaded
• Repo-level agents: Loaded from remote, no warnings/errors

Test 3: Remote configured with no .github/agents folder, but .github/agents folder exists locally

• Command: copilot
• Command inside copilot: /agents
• User-level agents: Still not loaded
• Repo-level agents: Loaded from local, but with warning "could not load remote agents for pietrobondioli/ai-tooling: server returned 404:"

Test 4: No .github/agents folder in remote/local

• Command: copilot
• Command inside copilot: /agents
• User-level agents: Still not loaded
• Repo-level agents: Not loaded (as expected), with error "could not load remote agents for pietrobondioli/ai-tooling: server returned 404:"

Summary

In all four scenarios, my user-level custom agents in ~/.copilot/agents were present but never loaded. The CLI appears to only check for repository-level definitions in .github/agents, I tested all these scenarios because my initial guess was that errors during repo-level discovery were affecting user-level discovery - but that doesn't seem to be the case.

Expected behavior

According to the v0.0.353 release notes, agent definitions should be loaded from both:

• User-level: ~/.copilot/agents
• Repository-level: .github/agents

Additional context

• Operating system: Arch Linux
• CPU architecture: x86_64
• Terminal emulator: kitty 0.43.1
• Shell: zsh 5.9

Logs:

2025-11-02T17:58:27.137Z [DEBUG] Fetched Copilot URL: 200 https://api.business.githubcopilot.com
2025-11-02T17:58:27.137Z [DEBUG] Creating copilot-client for integration ID copilot-developer-cli with token authentication. User-agent: copilot/0.0.353 (linux v25.1.0) OpenAI/5.20.1
2025-11-02T17:58:27.221Z [DEBUG] Fetched Copilot URL: 200 https://api.business.githubcopilot.com
2025-11-02T17:58:27.919Z [DEBUG] Successfully listed 31 models
2025-11-02T17:58:28.567Z [DEBUG] Fetched Copilot URL: 200 https://api.business.githubcopilot.com
2025-11-02T17:58:28.567Z [LOG] Starting remote MCP client for github-mcp-server with url: https://api.business.githubcopilot.com/mcp/readonly
2025-11-02T17:58:28.567Z [LOG] Creating MCP client for github-mcp-server...
2025-11-02T17:58:28.568Z [LOG] Connecting MCP client for github-mcp-server...
2025-11-02T17:58:28.894Z [LOG] MCP client for github-mcp-server connected, took 326ms
2025-11-02T17:58:28.894Z [LOG] Started MCP client for remote server github-mcp-server
2025-11-02T17:58:28.894Z [LOG] GitHub MCP server configured after authentication

[williammartin]

Hey, thanks a lot for the investigation. Any possibility you have XDG_CONFIG_HOME set in your environment?

[pietrobondioli]

hey! yes, I do:

[williammartin]

Put the agent files under $XDG_CONFIG_HOME/.copilot/agents. The release notes are correct to the extent that ~/.copilot is the default config location that we look under, but we respect $XDG_CONFIG_HOME as well.

[LasseHels]

I have the same issue.

I have custom agent definitions in ~/.copilot/agents:

➜  ~ ls ~/.copilot/agents                        
brainstorm.md   debug.md        execute-plan.md flaky-tests.md  racy.md         review.md

I am unable to load them:

➜  ~ copilot
 Welcome to GitHub Copilot CLI
 Version 0.0.354 · Commit 076bd172b

 Copilot can write, test and debug code right from your terminal. Describe a task to get started or enter ? for help. Copilot uses AI, check for mistakes.

 ● Connected to GitHub MCP Server

 ● Logged in as user: LasseHels

 ● No available custom agents. <----- :(

 ~                                                                                                                                           claude-sonnet-4.5 (1x)
 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 >  Enter @ to mention files or / for commands
 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Ctrl+c Exit · Ctrl+r Expand recent

Note that the above command was run in my home directory and not in a git repository directory.

Logs:

2025-11-05T13:44:31.434Z [INFO] Starting Copilot CLI: 0.0.354
Commit: 076bd172b
2025-11-05T13:44:31.435Z [INFO] Node.js version: v23.11.0
2025-11-05T13:44:31.680Z [INFO] Login status unknown
2025-11-05T13:44:31.702Z [ERROR] Error checking for updates: TypeError: Cannot read properties of undefined (reading 'paths')
2025-11-05T13:44:32.226Z [DEBUG] Fetched Copilot URL for LasseHels from https://api.github.com/graphql: 200 https://api.business.githubcopilot.com
2025-11-05T13:44:32.227Z [LOG] Starting remote MCP client for github-mcp-server with url: https://api.business.githubcopilot.com/mcp/readonly
2025-11-05T13:44:32.227Z [LOG] Creating MCP client for github-mcp-server...
2025-11-05T13:44:32.229Z [LOG] Connecting MCP client for github-mcp-server...
2025-11-05T13:44:33.455Z [LOG] MCP client for github-mcp-server connected, took 1226ms
2025-11-05T13:44:33.455Z [LOG] Started MCP client for remote server github-mcp-server
2025-11-05T13:44:33.455Z [LOG] GitHub MCP server configured after authentication
2025-11-05T13:44:33.465Z [INFO] Logged in as user: LasseHels
2025-11-05T13:44:33.804Z [DEBUG] Fetched Copilot URL for LasseHels from https://api.github.com/graphql: 200 https://api.business.githubcopilot.com
2025-11-05T13:44:33.804Z [DEBUG] Creating copilot-client for integration ID copilot-developer-cli with token authentication. User-agent: copilot/0.0.354 (darwin v23.11.0) OpenAI/5.20.1
2025-11-05T13:44:34.083Z [DEBUG] Successfully listed 26 models

---

Running Copilot in a git repository directory and trying to load custom agents gives a different error:

➜  some-repository git:(main) copilot               
 Welcome to GitHub Copilot CLI
 Version 0.0.354 · Commit 076bd172b

 Copilot can write, test and debug code right from your terminal. Describe a task to get started or enter ? for help. Copilot uses AI, check for mistakes.

 ● Connected to GitHub MCP Server

 ● Logged in as user: LasseHels

 ✗ No available custom agents:
   • could not load remote agents for Maersk-Global/some-repository: server returned 404: 

 ~/Projects/some-repository[⎇ main]                                                                                                      claude-sonnet-4.5 (1x)
 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 >  Enter @ to mention files or / for commands
 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Ctrl+c Exit · Ctrl+r Expand recent

This project does not have any custom agents defined, but I would still expect to be able to load my personal agents from ~/.copilot/agents.

Logs:

2025-11-05T13:54:23.513Z [INFO] Starting Copilot CLI: 0.0.354
Commit: 076bd172b
2025-11-05T13:54:23.514Z [INFO] Node.js version: v23.11.0
2025-11-05T13:54:23.754Z [INFO] Login status unknown
2025-11-05T13:54:23.773Z [ERROR] Error checking for updates: TypeError: Cannot read properties of undefined (reading 'paths')
2025-11-05T13:54:24.521Z [DEBUG] Fetched Copilot URL for LasseHels from https://api.github.com/graphql: 200 https://api.business.githubcopilot.com
2025-11-05T13:54:24.522Z [LOG] Starting remote MCP client for github-mcp-server with url: https://api.business.githubcopilot.com/mcp/readonly
2025-11-05T13:54:24.522Z [LOG] Creating MCP client for github-mcp-server...
2025-11-05T13:54:24.526Z [LOG] Connecting MCP client for github-mcp-server...
2025-11-05T13:54:25.451Z [LOG] MCP client for github-mcp-server connected, took 925ms
2025-11-05T13:54:25.451Z [LOG] Started MCP client for remote server github-mcp-server
2025-11-05T13:54:25.451Z [LOG] GitHub MCP server configured after authentication
2025-11-05T13:54:25.455Z [INFO] Logged in as user: LasseHels
2025-11-05T13:54:25.737Z [DEBUG] Fetched Copilot URL for LasseHels from https://api.github.com/graphql: 200 https://api.business.githubcopilot.com
2025-11-05T13:54:25.738Z [DEBUG] Creating copilot-client for integration ID copilot-developer-cli with token authentication. User-agent: copilot/0.0.354 (darwin v23.11.0) OpenAI/5.20.1
2025-11-05T13:54:25.832Z [DEBUG] Fetched Copilot URL for LasseHels from https://api.github.com/graphql: 200 https://api.business.githubcopilot.com
2025-11-05T13:54:25.894Z [DEBUG] Successfully listed 26 models
2025-11-05T13:54:26.949Z [ERROR] Request to GitHub API at https://api.business.githubcopilot.com/agents/swe/custom-agents/Maersk-Global/some-repository?exclude_invalid_config=true failed with status 404 (request ID: 84E8:18F621:1155BDF:1378518:690B5712), body: Not Found

2025-11-05T13:54:26.950Z [WARNING] Failed to load custom agents for Maersk-Global/some-repository: Not Found

I don't have $XDG_CONFIG_HOME set.

---

Here is an example of one of the custom agents I would expect to work:

➜  ~ cat ~/.copilot/agents/brainstorm.md                                  
---
name: Brainstormer
description: Brainstorm an issue or the implementation of a new feature.
---

# Brainstorming Ideas Into Designs

Some prompt definition.

[williammartin]

● No available custom agents. <----- :(

Much sad.

• could not load remote agents for Maersk-Global/some-repository: server returned 404:

I actually just filed a bug with the API team to resolve this before I read your comment. They decided to use 404 to represent no agents, but they are going to change that.

This project does not have any custom agents defined, but I would still expect to be able to load my personal agents from ~/.copilot/agents.

I would also expect that you can do that. Just to double check, what else is under ~/.copilot for you?

[LasseHels]

Just to double check, what else is under ~/.copilot for you?

Click me

➜  ~ ls -la ~/.copilot/*
-rw-------  1 lasse.hels  staff  16738 Nov  6 08:27 /Users/lasse.hels/.copilot/command-history-state.json
-rw-------  1 lasse.hels  staff    657 Nov  6 08:27 /Users/lasse.hels/.copilot/config.json
lrwxr-xr-x  1 lasse.hels  staff     53 Oct 24 09:59 /Users/lasse.hels/.copilot/copilot-instructions.md -> /Users/lasse.hels/Projects/conventions/conventions.md

/Users/lasse.hels/.copilot/agents:
total 0
drwxr-xr-x  8 lasse.hels  staff  256 Nov  6 08:28 .
drwx------  9 lasse.hels  staff  288 Nov  5 14:28 ..
lrwxr-xr-x  1 lasse.hels  staff   59 Nov  5 14:29 brainstorm.md -> /Users/lasse.hels/Projects/conventions/skills/brainstorm.md
lrwxr-xr-x  1 lasse.hels  staff   54 Nov  5 14:29 debug.md -> /Users/lasse.hels/Projects/conventions/skills/debug.md
lrwxr-xr-x  1 lasse.hels  staff   61 Nov  5 14:29 execute-plan.md -> /Users/lasse.hels/Projects/conventions/skills/execute-plan.md
lrwxr-xr-x  1 lasse.hels  staff   60 Nov  5 14:29 flaky-tests.md -> /Users/lasse.hels/Projects/conventions/skills/flaky-tests.md
lrwxr-xr-x  1 lasse.hels  staff   53 Nov  5 14:29 racy.md -> /Users/lasse.hels/Projects/conventions/skills/racy.md
lrwxr-xr-x  1 lasse.hels  staff   55 Nov  5 14:29 review.md -> /Users/lasse.hels/Projects/conventions/skills/review.md

/Users/lasse.hels/.copilot/history-session-state:
total 19288
drwx------  35 lasse.hels  staff     1120 Oct 16 12:04 .
drwx------   9 lasse.hels  staff      288 Nov  5 14:28 ..
# A bunch of session JSON files.

/Users/lasse.hels/.copilot/logs:
total 3312
drwxr-xr-x  152 lasse.hels  staff   4864 Nov  6 08:27 .
drwx------    9 lasse.hels  staff    288 Nov  5 14:28 ..
# A bunch of log files.

/Users/lasse.hels/.copilot/session-state:
total 32504
drwx------  69 lasse.hels  staff     2208 Nov  5 13:12 .
drwx------   9 lasse.hels  staff      288 Nov  5 14:28 ..
# A bunch of session JSON files.

While checking the contents of ~/.copilot, I figured that the issue might be that the files in my ~/.copilot/agents directory are symlinks to files elsewhere in my system.

This seems to be the crux of the issue. If I add a new ~/.copilot/agents/banana.md file (that is not a symlink), then I can access the agent:

➜  ~ ls -la ~/.copilot/agents/*
lrwxr-xr-x  1 lasse.hels  staff  59 Nov  5 14:29 /Users/lasse.hels/.copilot/agents/brainstorm.md -> /Users/lasse.hels/Projects/conventions/skills/brainstorm.md
lrwxr-xr-x  1 lasse.hels  staff  54 Nov  5 14:29 /Users/lasse.hels/.copilot/agents/debug.md -> /Users/lasse.hels/Projects/conventions/skills/debug.md
lrwxr-xr-x  1 lasse.hels  staff  61 Nov  5 14:29 /Users/lasse.hels/.copilot/agents/execute-plan.md -> /Users/lasse.hels/Projects/conventions/skills/execute-plan.md
lrwxr-xr-x  1 lasse.hels  staff  60 Nov  5 14:29 /Users/lasse.hels/.copilot/agents/flaky-tests.md -> /Users/lasse.hels/Projects/conventions/skills/flaky-tests.md
lrwxr-xr-x  1 lasse.hels  staff  53 Nov  5 14:29 /Users/lasse.hels/.copilot/agents/racy.md -> /Users/lasse.hels/Projects/conventions/skills/racy.md
lrwxr-xr-x  1 lasse.hels  staff  55 Nov  5 14:29 /Users/lasse.hels/.copilot/agents/review.md -> /Users/lasse.hels/Projects/conventions/skills/review.md
➜  ~ mv ./banana.md ~/.copilot/agents/banana.md
➜  ~ ls -la ~/.copilot/agents/*
-rw-r--r--  1 lasse.hels  staff  82 Nov  6 08:27 /Users/lasse.hels/.copilot/agents/banana.md
lrwxr-xr-x  1 lasse.hels  staff  59 Nov  5 14:29 /Users/lasse.hels/.copilot/agents/brainstorm.md -> /Users/lasse.hels/Projects/conventions/skills/brainstorm.md
lrwxr-xr-x  1 lasse.hels  staff  54 Nov  5 14:29 /Users/lasse.hels/.copilot/agents/debug.md -> /Users/lasse.hels/Projects/conventions/skills/debug.md
lrwxr-xr-x  1 lasse.hels  staff  61 Nov  5 14:29 /Users/lasse.hels/.copilot/agents/execute-plan.md -> /Users/lasse.hels/Projects/conventions/skills/execute-plan.md
lrwxr-xr-x  1 lasse.hels  staff  60 Nov  5 14:29 /Users/lasse.hels/.copilot/agents/flaky-tests.md -> /Users/lasse.hels/Projects/conventions/skills/flaky-tests.md
lrwxr-xr-x  1 lasse.hels  staff  53 Nov  5 14:29 /Users/lasse.hels/.copilot/agents/racy.md -> /Users/lasse.hels/Projects/conventions/skills/racy.md
lrwxr-xr-x  1 lasse.hels  staff  55 Nov  5 14:29 /Users/lasse.hels/.copilot/agents/review.md -> /Users/lasse.hels/Projects/conventions/skills/review.md
➜  ~ copilot
 Welcome to GitHub Copilot CLI
 Version 0.0.354 · Commit 076bd172b

 Copilot can write, test and debug code right from your terminal. Describe a task to get started or enter ? for help. Copilot uses AI, check for mistakes.

 ● Connected to GitHub MCP Server

 ● Logged in as user: LasseHels

 Select Custom Agent

 ❯ 1. Banana
   2. Cancel (Esc)

 Confirm with number keys or ↑↓ keys and Enter, Cancel with Esc

Copilot CLI is not the only agentic tool I use, so I have my skill/agent files in a central conventions repository that I can then reference where necessary. Perhaps Copilot CLI could allow reading custom agent files from symlinks? Another approach could be that the directory from which to load custom agents locally could be configured.

[williammartin]

symlinks

Yeh that's exactly it. In getting the initial MVP out for custom agents before GitHub Universe, I decided I didn't have time to fully evaluate whether there were any security concerns if we traversed symlinks here. I suspected the answer was no, but I didn't want to rush it. I'll create an issue to track that work later today, I suspect you won't be the only person who wants this. Thanks a lot for the investigation!