Copilot agents question

[jedrekdomanski]

Select Topic Area

Question

Copilot Feature Area

Copilot Agent Mode

Body

I'm using VS Code and I am currently working in a workspace that includes a bunch of different projects and I wanted to create an agent that would be global to all my projects.
I've created my custom agent linux-engineer by using Generate agent option in VSCode and I got this in response:

The agent file is ready at ~/.github/agents/linux-engineer.agent.md. Example prompts to try:

@linux-engineer Write a bash script to rotate Nginx logs and reload the service
@linux-engineer Configure iptables to allow only ports 22, 80, 443 and drop everything else
@linux-engineer Set up an LVM volume group across two disks and mount it at /data
@linux-engineer Harden SSH on a new server — disable root login, enforce key-only auth

The file was created at ~/.github/agents/linux-engineer.agent.md
In VSCode settings these are my agents file location settings

.github/agents
.claude/agents
~/.copilot/agents
~/.github/agents

so it should read my agent file. I reloaded VSCode, I am in Agent mode and the frontmatter does include the name of the agent persona

---
name: linux-engineer
description: "Linux System Administrator and Engineer."

but when I start typing in the chat window @lin there is nothing like @linux-engineer. All I have is @ruby, @Terminal and a bunch of different option but my agent is not there. I've tried placing the agent file at the root of my project at .github/agents/linux-engineer.agent.md, reloaded VS Code and still nothing.
Here's the listing of my agent files

ls ~/.github/agents/
linux-engineer.agent.md

How do I use my newly created agent?

[Shiven0504]

Hii @jedrekdomanski , this is a common issue when getting started with custom agents. Heres what you can do:

First make sure the file is in the right folder

Your linux-engineer.agent.md file needs to live inside .github/agents/ in your project:

your-project/
└── .github/
└── agents/
└── linux-engineer.agent.md

If it ended up somewhere else, just move it there and then simply reload vs code. After moving the file, press Ctrl+Shift+P (or Cmd+Shift+P on Mac), type "Reload Window", and hit Enter. This lets Copilot discover the new agent.

After that you can switch to Agent mode. Also at the top of the chat panel, there's a mode dropdown so just make sure it's set to Agent, not "Ask" or "Edit" because custom agents only show up in Agent mode.

Once you've done those three things, type @lin and you should see your @linux-engineer pop up.

[jedrekdomanski]

@Shiven0504 But my file locations settings are:

.github/agents
.claude/agents
~/.copilot/agents
~/.github/agents

so it should read my agent file. Does it have to be specifically in
your-project/
└── .github/
└── agents/
└── linux-engineer.agent.md
?

[Shiven0504]

Yeah thats totally fine, it doesn't have to be specifically in your project's .github/agents/ folder. Since you've configured multiple agent file locations, any of these should work. So if your file is already in one of those folders, the location is fine.

In that case, you can try two things:

1. Reload vs code - press Ctrl+Shift+P, type "Reload Window", and hit Enter. Sometimes vs code just needs a nudge to pick up new agent files.
2. Make sure you're in Agent mode - at the top of the chat panel, switch the dropdown to Agent. Custom agents won't show up in "Ask" or "Edit" mode.

If it still doesn't appear after that, try double-checking the frontmatter at the top has a valid name field:
name: linux-engineer
description: "Linux systems engineering assistant"

That name is what vs code uses to register the @linux-engineer mention. If it's missing or has a typo, the agent won't show up.

[jedrekdomanski]

I did reload VSCode, I am in Agent mode and the frontmatter does include the name of the agent persona

---
name: linux-engineer
description: "Linux System Administrator and Engineer.

but the agent is not available in the chat window. What am I missing? Any other ideas?

[Shiven0504]

can you verify the file is sitting directly inside one of your configured locations? try running ls ~/.copilot/agents/ and
ls ~/.github/agents/ or check if its in your workspace root.

secondly, go to settings and make sure chat.agent.enabled is turned on.

if still nothing works, I suggest putting the file directly in your project folder:

[jedrekdomanski]

My Chat Agent is enabled

Here's the listing of folders you asked about

ls ~/.copilot/agents/
rails-engineer.agent.md

ls ~/.github/agents/
linux-engineer.agent.md

I've tried placing the agent file at the root of my project at .github/agents/linux-engineer.agent.md, reloaded VS Code and still nothing.
There is also ~/.copilot/agents/rails-engineer.agent.md agent which, by the way, is also not available in chat. Any ideas?

[chamithsilva10]

Custom Agents in VS Code Copilot

Guide on how to create, place, and invoke custom .agent.md files so they actually appear in VS Code Copilot Chat.

---

The Problem

You created a custom agent and placed it at:

~/.github/agents/linux-engineer.agent.md

You reloaded VS Code — but it does not appear in the Copilot Chat dropdown.

Below are the common causes and fixes.

---

Root Cause #1 — Tilde (~) Is Not Expanded

VS Code does NOT expand ~ to your home directory in chat.agentFilesLocations.

It treats it as a literal path, so the file is never discovered.

Fix

Use absolute paths in settings.json.

"chat.agentFilesLocations": [
  ".github/agents",
  ".claude/agents",
  "/home/yourusername/.copilot/agents",
  "/home/yourusername/.github/agents"
]

Replace yourusername with your actual Linux username.

---

Root Cause #2 — Malformed Frontmatter

Your agent file may contain invalid YAML frontmatter.
If YAML is invalid, VS Code silently skips the file.

Bad Example

---
name: linux-engineer
description: "Linux System Administrator and Engineer.
---

The string is not closed.

Good Example

---
name: linux-engineer
description: "Linux System Administrator and Engineer."
---

---

Root Cause #3 — Wrong Invocation Method

Custom agents are NOT invoked with @agentname in chat.

The @ examples shown by Copilot are for use inside an agent session, not for starting one.

Correct Method

1. Open Copilot Chat
2. Look at the agent picker dropdown at the bottom
3. Select your custom agent

Then start chatting normally.

---

Recommended Setup — Let VS Code Create It

Instead of creating files manually, use VS Code's built-in command.

Steps

1. Open Command Palette

Ctrl + Shift + P

2. Run:

Chat: New Custom Agent

3. Choose:

User Profile

(not Workspace if you want a global agent)

4. VS Code automatically creates the agent file in the correct location.

5. Reload the window:

Developer: Reload Window

---

Checklist

Check	Status	Fix
No ~ in settings paths	❌ Failing	Use absolute paths
Frontmatter YAML valid	❌ Failing	Close description string
File extension .agent.md	✅ Pass	—
Window reloaded	✅ Pass	—
Using dropdown (not @)	❌ Failing	Use agent picker

---

Example Prompts (After Agent Is Active)

First select linux-engineer from the dropdown.

Then type prompts normally:

Write a bash script to rotate Nginx logs and reload the service

Configure iptables to allow only ports 22, 80, 443 and drop everything else

Set up an LVM volume group across two disks and mount it at /data

Harden SSH — disable root login, enforce key-only authentication

---

File Naming Convention

Your agent file should look like this:

linux-engineer.agent.md

Example location:

~/.copilot/agents/linux-engineer.agent.md

---

Summary

To make custom Copilot agents work:

• Use absolute paths
• Ensure valid YAML frontmatter
• Use .agent.md extension
• Reload VS Code
• Select agent from dropdown

Then your custom agent will appear and work correctly.

---

[jedrekdomanski]

Thank you for AI-generated response :D

I do see two agents when I click the dropdown

So what is an agent sessions? Don't I have already one running after I clicked New Chat?

Custom agents are NOT invoked with @agentname in chat.

The @ examples shown by Copilot are for use inside an agent session, not for starting one.

I'm not sure I follow. Isn't the chat window a chat session? I'm confused.

[Shiven0504]

Agent mode is the one you select at the bottom of the chat panel. When you're in agent mode, you're basically in an "agent session." This is where Copilot can run commands, edit files etc. Custom agents are your .agent.md files like linux-engineer.

When you're in Agent mode, you can either just describe your task naturally and Copilot will use the relevant agent's instructions or reference it directly in your prompt like: "Using the linux-engineer agent write a bash script". Custom agents provide instructions and context to agent mode rather than being a separate chat participant that you invoke with @.

[Shiven0504]

btw did it resolve ?

[jedrekdomanski]

So what is chat participant and what did the Copilot mean by giving me sample prompts such as @linux-engineer Write a bash script to rotate Nginx logs and reload the service so I can understand it better? When would I use the participant with "@"?

[jedrekdomanski]

btw did it resolve ?

Yes, I see both agents on the bottom when I click the dropdown.

[Shiven0504]

you can think of chat participant as a built-in specialist inside copilot chat. These are the ones you see when you type @, such as - @workspace will know about your entire project structure, @Terminal will know about your terminal and shell commands and so on. Remember chat participants are built into copilot by github so you cant create your own chat participants.

Custom agents (like your linux-engineer.agent.md file) are not chat participants. They work differently because they provide instructions and persona to Agent mode. Think of them as a custom system prompt that shapes how Copilot behaves during an agent session.

[jedrekdomanski]

Thank you, I understand. I am still confused why Copilot suggested to me to type @linux-engineer Write a bash script to make a backup of my database, though. That's the reason why I made this post actually. Is this a bug?

[Shiven0504]

Yeah I would rather say its a bug or at least very misleading behavior from copilot. When you use the "Generate agent" feature, copilot autogenerates those @agentname example prompts as if they'll work like built-in chat participants like @workspace or @Terminal

But custom .agent.md agents simply don't work that way cuz they aren't mentionable with @, so the example that copilot gave you would never actually work as shown. It's the generated output giving you the wrong impression of how to use the feature.