Skip to main content
While the MCP Server provides the easiest installation method, you can also manually install agents, instructions, and skills by copying files directly into your project.

​
File Types and Locations

Awesome GitHub Copilot provides three main types of customizations, each with specific file naming conventions and locations:

Agents

Files ending in .agent.md that define specialized AI personas

Instructions

Files ending in .instructions.md that provide coding standards

Skills

Folders containing SKILL.md with bundled resources

​
Installing Agents

Agents are specialized GitHub Copilot configurations that transform the assistant into domain-specific experts.
1

Choose an agent

Browse the Agents Catalog or the GitHub repository to find an agent.
2

Create agents directory

Create a .github/copilot/agents/ directory in your project root:
mkdir -p .github/copilot/agents
3

Copy the agent file

Download the .agent.md file and place it in the agents directory:
# Example: Installing the Python expert agent
curl -o .github/copilot/agents/python-expert.agent.md \
  https://raw.githubusercontent.com/github/awesome-copilot/main/agents/python-expert.agent.md
Or manually copy the file from the repository.
4

Verify the installation

The agent file must:
  • Have the .agent.md extension
  • Use lowercase with hyphens (e.g., python-expert.agent.md)
  • Include required frontmatter with description and name fields
---
description: 'Expert assistant for Python development'
name: 'Python Expert'
model: 'gpt-4.1'
tools: ['codebase', 'terminal']
---

​
Agent File Structure

project/
└── .github/
    └── copilot/
        └── agents/
            ├── python-expert.agent.md
            ├── react-specialist.agent.md
            └── devops-helper.agent.md

​
Installing Instructions

Instructions provide coding standards and best practices that automatically apply to specific file patterns.
1

Choose instructions

Browse the Instructions Catalog or the GitHub repository.
2

Create instructions directory

Create a .github/copilot/instructions/ directory:
mkdir -p .github/copilot/instructions
3

Copy the instruction file

Download the .instructions.md file:
# Example: Installing React instructions
curl -o .github/copilot/instructions/react.instructions.md \
  https://raw.githubusercontent.com/github/awesome-copilot/main/instructions/react.instructions.md
4

Verify the installation

The instruction file must:
  • Have the .instructions.md extension
  • Use lowercase with hyphens
  • Include required frontmatter with description and applyTo fields
---
description: 'React best practices and coding standards'
applyTo: '**.jsx, **.tsx'
---

​
Instructions File Structure

project/
└── .github/
    └── copilot/
        └── instructions/
            ├── react.instructions.md
            ├── typescript.instructions.md
            └── python-django.instructions.md

​
Installing Skills

Skills are self-contained folders with instructions and bundled resources for specialized tasks.
1

Choose a skill

Browse the Skills Catalog or the GitHub repository.
2

Create skills directory

Create a .github/copilot/skills/ directory:
mkdir -p .github/copilot/skills
3

Copy the entire skill folder

Download the complete skill folder with all bundled assets:
# Example: Installing the mintlify skill
git clone --depth 1 --filter=blob:none --sparse \
  https://github.com/github/awesome-copilot.git temp-repo
cd temp-repo
git sparse-checkout set skills/mintlify
cp -r skills/mintlify ../.github/copilot/skills/
cd ..
rm -rf temp-repo
Or manually download the folder from the repository.
4

Verify the installation

Each skill folder must:
  • Contain a SKILL.md file
  • Use lowercase folder name with hyphens
  • SKILL.md must have name and description in frontmatter
  • The name field must match the folder name
---
name: mintlify
description: 'Comprehensive reference for building Mintlify documentation sites'
---

​
Skills File Structure

project/
└── .github/
    └── copilot/
        └── skills/
            ├── mintlify/
            │   ├── SKILL.md
            │   ├── components/
            │   └── references/
            └── web-design-reviewer/
                ├── SKILL.md
                └── references/
Skills may include bundled assets like scripts, templates, and reference files. Make sure to copy the entire skill folder to preserve these resources.

​
Naming Conventions

All files must follow these naming rules:
Incorrect file naming will prevent GitHub Copilot from recognizing your customizations.
TypeConventionExamples
Agentslowercase-with-hyphens.agent.mdpython-expert.agent.md
react-specialist.agent.md
Instructionslowercase-with-hyphens.instructions.mdtypescript.instructions.md
python-django.instructions.md
Skillslowercase-with-hyphens/ foldermintlify/
web-design-reviewer/

​
Frontmatter Requirements

All customizations require YAML frontmatter at the top of the file: 
---
description: 'Brief description of the agent and its purpose'
name: 'Human Readable Agent Name'
model: 'gpt-4.1'  # strongly recommended
tools: ['codebase', 'terminal']  # recommended
---
  • Always wrap description field values in single quotes
  • The skill’s name field must match the folder name exactly
  • Use lowercase with hyphens for all file and folder names

​
Using Installed Customizations

​
Activating Agents

Once installed, agents appear in the GitHub Copilot agent selector:
  1. Open GitHub Copilot Chat
  2. Type @ to see available agents
  3. Select your custom agent from the list

​
Using Instructions

Instructions automatically apply to files matching the applyTo patterns. No manual activation needed.

​
Invoking Skills

Skills are loaded when referenced by name in conversations: 
@github load the mintlify skill

​
Workspace vs Global Installation

Workspace Installation

Install in .github/copilot/ within a project to share customizations with the team via version control.Best for: Team standards, project-specific agents

Global Installation

Install in your user configuration directory to use customizations across all projects.Best for: Personal preferences, cross-project tools
VS Code / VS Code Insiders:
  • Windows: %APPDATA%\Code\User\globalStorage\github.copilot\
  • macOS: ~/Library/Application Support/Code/User/globalStorage/github.copilot/
  • Linux: ~/.config/Code/User/globalStorage/github.copilot/
Visual Studio: Configure through Visual Studio settings (Tools → Options → GitHub Copilot)

​
Updating Customizations

To update a customization:
  1. Download the latest version from the repository
  2. Replace the existing file or folder
  3. Restart GitHub Copilot or reload your editor window
Customizations are loaded when GitHub Copilot starts. You may need to reload your editor window for changes to take effect.

​
Troubleshooting

Check:
  • File has .agent.md extension
  • File is in .github/copilot/agents/ directory
  • Frontmatter includes description and name fields
  • File name uses lowercase with hyphens
Fix: Verify frontmatter syntax and reload editor window
Check:
  • File has .instructions.md extension
  • File is in .github/copilot/instructions/ directory
  • Frontmatter includes description and applyTo fields
  • applyTo pattern matches your file type
Example applyTo patterns:
applyTo: '**.js, **.jsx'  # JavaScript files
applyTo: '**.py'          # Python files
applyTo: '**'             # All files
Check:
  • Folder is in .github/copilot/skills/ directory
  • Folder contains a SKILL.md file (not skill.md)
  • SKILL.md has frontmatter with name and description
  • The name field matches the folder name exactly
  • Folder name uses lowercase with hyphens
Fix: Ensure all bundled assets are copied with the skill folder

​
What’s Next?

Using Agents

Learn how to use custom agents in your workflow

Using Instructions

Understand how instructions customize Copilot behavior

Using Skills

Explore how to invoke and use skills

Browse Catalog

Discover available agents, instructions, and skills

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us