Starter Guide
Using AI in VS Code: Where Agents & Skills Live
If you are new to AI features in VS Code, this page walks you through the storage model behind agents and skills, the difference between personal and project-level setup, and what a workspace actually means in day-to-day use.
The Basics
What Are Agents & Skills?
Before diving into where things are stored, here is what these two concepts actually are.
Agents
An agent is a custom personality you give to Copilot. It is defined in a single
file called .agent.md that tells Copilot who it should act as, what it should focus on,
and which skills it can use.
Think of an agent like a job description: it tells Copilot what role to play, what rules to follow, and what tools (skills) are available for the job.
Skills
A skill is a reusable set of instructions stored in a file called SKILL.md.
Skills give agents specialized capabilities — like knowing how to parse logs, generate tests,
or follow a specific coding standard.
Think of a skill like a reference manual an employee keeps at their desk: when a specific type of task comes up, they pull out the relevant manual and follow those instructions.
Core Concept
What Is a Workspace?
Understanding this concept is essential because it determines where your agents and skills are stored and who can see them.
📁 The Desktop Folder Analogy
Imagine your physical desk has several project folders stacked on it. Each folder contains everything related to one project — notes, documents, checklists, reference materials.
When you pick up a folder and open it to start working, that folder becomes your workspace. Everything inside it is available to you. Everything in the other folders on your desk is not — you would have to close this folder and open a different one to access those materials.
VS Code works the same way. When you use File → Open Folder and select a folder on your computer, that folder and everything inside it becomes your workspace. VS Code's file explorer shows you what is in that folder. Copilot's agents and skills that live inside that folder are now active and available.
Why This Matters for Agents & Skills
Because a workspace is tied to a specific folder, any agent or skill files you put inside that folder are workspace-level — they only work when that folder is open. This is how teams share agents: everyone who opens the same project folder gets the same agents and skills automatically.
But you can also store agents and skills in a special folder in your home directory (outside any project). These are user-level — they follow you everywhere, regardless of which project folder you have open.
File Locations
Where Agents Live
Agent files are named .agent.md and can be stored in two places depending on who needs access.
Project-Level Agents
.github/agents/<agent-name>.agent.md
This path is relative to your project folder. When you place an agent file here, it becomes available to everyone who opens this project. The file is version-controlled alongside your code, so changes are tracked and shared through Git.
Best for: team standards, project-specific workflows, shared review agents.
Personal Agents
~/.copilot/agents/<agent-name>.agent.md
The ~ symbol means your home directory — this is a folder on your computer
that belongs to your user account. Agents stored here are only available to you,
but they work across every project you open in VS Code.
Best for: personal preferences, private workflows, agents you want available everywhere.
File Locations
Where Skills Live
Skills follow the same two-location pattern as agents. Each skill lives inside its own named folder.
Project-Level Skills
.github/skills/<skill-name>/SKILL.md
Workspace skills are stored inside the project folder under .github/skills/.
Each skill gets its own sub-folder with a SKILL.md file inside it.
These skills are shared with the team through version control.
Best for: team coding standards, project-specific linting rules, shared troubleshooting procedures.
Personal Skills
~/.copilot/skills/<skill-name>/SKILL.md
Personal skills live in your home directory and travel with you across every project. No one else can see or use these skills — they are part of your personal Copilot setup.
Best for: your preferred code style, personal documentation templates, private utility skills.
Side by Side
User-Defined vs Workspace-Defined
Here is a direct comparison to help you decide where to put your agents and skills.
👤 User-Defined
- Stored in
~/.copilot/(your home directory)- Who sees it
- Only you
- Works in
- Every project you open
- Version controlled
- No — it lives outside any repository
- Shared with team
- No — personal to your machine
- Best for
- Personal preferences, private workflows, agents and skills you always want available
📂 Workspace-Defined
- Stored in
.github/(inside the project folder)- Who sees it
- Everyone who opens this project
- Works in
- Only this specific project
- Version controlled
- Yes — tracked by Git with your code
- Shared with team
- Yes — automatically via the repository
- Best for
- Team standards, project-specific agents, shared review and troubleshooting workflows
At a Glance
Quick Visual Map
This shows both storage locations side by side so you can see the full picture.
👤 Your Home Directory (User-Level)
~
└── .copilot/
├── agents/
│ ├── my-reviewer.agent.md
│ └── my-helper.agent.md
└── skills/
├── my-code-style/
│ └── SKILL.md
└── my-log-parser/
└── SKILL.md
📂 Your Project Folder (Workspace-Level)
my-project/ ├── .github/ │ ├── agents/ │ │ ├── team-reviewer.agent.md │ │ └── qa-tester.agent.md │ ├── skills/ │ │ ├── coding-standards/ │ │ │ └── SKILL.md │ │ └── log-troubleshooter/ │ │ └── SKILL.md │ └── copilot-instructions.md ├── src/ │ └── ... └── README.md
One More Thing: copilot-instructions.md
You may also see a file called copilot-instructions.md inside .github/.
This is a repo-wide instruction file that applies to all agents working in the project —
it sets baseline rules and context that every agent follows. For more detail, see the
Quick Reference on the main page.