Setting Up GitHub Copilot Agent Skills in Your Repository

Why Teach Copilot New Skills?

The Power of Specialized Instructions

Want Copilot to do more than just autocomplete?

If you’re ready to teach Copilot some new tricks, Agent Skills are your answer. Built on the agentskills.io open standard, a skill is a specialized folder of instructions and tools that Copilot only opens when it’s actually relevant to what you’re working on. It’s like having a smart assistant who knows exactly which reference book to grab off the shelf instead of dumping your entire library on the desk every time.

Smart Context Loading

Here’s the thing: loading everything at once would slow Copilot down and clutter its “brain” with stuff it doesn’t need right now. Agent Skills use progressive disclosure to load targeted context only when it matters. You get faster responses that actually make sense for what you’re doing.

The Problem: Generic AI Responses

One-Size-Fits-All Limitations

What’s the issue?

Let’s be honest: out of the box, Copilot is helpful but pretty generic. It doesn’t know about your team’s specific workflows, your project’s naming conventions, or those specialized tasks you run every week. So you find yourself typing the same explanations over and over, like you’re training a goldfish.

Context Overload

When you try to explain everything upfront, two problems pop up. First, it slows everything down. Second, Copilot’s responses get muddy because it’s trying to juggle too much information at once.

Repetitive Instructions

Without skills, every new coding session feels like Groundhog Day. You’re constantly re-explaining project-specific patterns, and it gets old fast.

The Solution: Repository-Based Agent Skills

Understanding Agent Skills

Here’s how to fix it

Agent Skills are specialized folders sitting in your repo (or user profile). They contain instructions, scripts, and tools that Copilot can tap into when needed. This approach is portable and works across multiple agents, including GitHub Copilot in VS Code, the CLI, and the coding agent.

The 3-Level Loading System (Progressive Disclosure)

To keep things efficient, Agent Skills use a three-level loading system:

1. Level 1: Skill Discovery (Always On): Copilot reads the name and description from the YAML frontmatter of every available SKILL.md. This is lightweight and helps it decide if a skill is relevant.
2. Level 2: Instructions Loading: When a skill matches your prompt, Copilot loads the full body of the SKILL.md file.
3. Level 3: Resource Access: Copilot only accesses additional files (scripts, templates, examples) in the skill directory as needed.

Persistent Knowledge

Once you’ve set up your skills, they live right there in your repository. That means everyone on your team gets access to the same knowledge base through the .github/skills directory.

Setting Up Your First Skill

Step 1: Create the Skills Directory

Quick setup steps

First, you need to pick where your skills folder lives. Recommended locations include:

• Project Skills: .github/skills/ (recommended) or .claude/skills/ (for backward compatibility).
• Personal Skills: ~/.copilot/skills/ (recommended) or ~/.claude/skills/.

Let’s say you pick .github/skills. Here’s how you’d set it up:

# Create the main skills directory
mkdir -p .github/skills

# Create a specific skill folder
mkdir .github/skills/image-resizer

Inside that main folder, create a subfolder for each specific skill you want. Name them something clear like image-resizer or webapp-testing.

Step 2: Write the SKILL.md File

This is where the magic happens

Every skill needs a SKILL.md file (must be uppercase) with YAML frontmatter at the top. The description is critical—it’s what level 1 discovery uses to trigger the skill.

Here’s a real example:

1
---
2
name: 'Image Resizer'
3
description: 'Automatically resizes and optimizes images for web use. Handles batch processing, maintains aspect ratios, and generates responsive image sets. Use this when working with image assets that need multiple sizes or optimization.'
4
---
5

6
# Image Resizing Workflow
7

8
First, I'll check what you're starting with:
9

10
- Look at source image dimensions and format
11
- Figure out what target sizes you need
12
- Make sure the output directory exists
13

14
Next, I'll handle the actual work using the [optimization script](./scripts/optimize.js).
15

16
Finally, I'll verify the output quality and file sizes.

Notice how the description is specific and detailed? That’s what ensures Copilot “picks up” the skill when you mention images or resizing.

Step 3: Add Scripts and Resources

What makes skills powerful

Here’s where things get really useful. You’re not limited to just instructions. You can bundle JavaScript scripts, templates, configuration files, whatever you need, right alongside your SKILL.md. Then reference them using relative paths.

Here’s what your folder structure might look like:

.github/skills/image-resizer/
├── SKILL.md
├── scripts/
│   ├── resize-images.js
│   └── optimize.js
└── templates/
    └── config-template.json

Then in your SKILL.md, you can tell Copilot about these files:

1
## Tools Available
2

3
To resize images, run: `./scripts/resize-images.js`
4

5
For optimization, use: `./scripts/optimize.js`
6

7
Configuration template: `./templates/config-template.json`

Now when you ask Copilot to resize images, it doesn’t just give you advice. It can actually tell you to run the script that’s already set up and tested. That’s way more useful than getting generic code suggestions every time.

Step 4: Enable Skills in VS Code

Activate the feature

Okay, heads up: this feature is currently in preview, so you’ll need to use VS Code Insiders to try it out. Here’s how to get it working:

1. Open VS Code (or VS Code Insiders)
2. Open Settings (press Cmd+, on Mac or Ctrl+, on Windows/Linux)
3. Search for “Agent Skills”
4. Ensure the experimental skill support is enabled

You can also enable it via .vscode/settings.json if you prefer:

1
{
2
  "chat.useAgentSkills": true
3
}

Once it’s enabled, test it out. Open Copilot chat and ask: “What skills do you have?” If everything’s set up right, Copilot should list your new skill and give you a quick rundown of what it does.

Real-World Skill Examples

Documentation Generator

Let’s say your team has a specific style guide for docs. You can create a skill that knows all your conventions and writes documentation that matches your standards every time.

1
---
2
name: 'Documentation Generator'
3
description: "Generates API documentation following the team's style guide. Includes TypeScript examples, parameter descriptions, and usage patterns. Use when documenting new functions or API endpoints."
4
---
5

6
## Documentation Format
7

8
Each function should include:
9

10
1. Brief description (one sentence)
11
2. Parameter table with types and descriptions
12
3. Return value explanation
13
4. Code example showing typical usage
14
5. Common gotchas or edge cases
15

16
Example template is in `./templates/api-doc.md`

Test Suite Builder

Tired of writing the same boilerplate test code? Build a skill that understands your testing patterns and can scaffold complete test suites.

1
---
2
name: 'Test Suite Builder'
3
description: 'Generates comprehensive test suites using Jest and React Testing Library. Covers happy paths, edge cases, and error scenarios. Use when creating tests for new components or utilities.'
4
---
5

6
## Test Structure
7

8
For each component/function, generate:
9

10
- Setup and teardown blocks
11
- Happy path tests
12
- Edge case coverage
13
- Error handling tests
14
- Mock setup when needed
15

16
Refer to `./examples/sample-test.spec.ts` for the pattern.

Code Review Checklist

You can even package your team’s code review standards into a skill that helps check PRs.

1
---
2
name: 'Code Review Checklist'
3
description: 'Provides a comprehensive code review checklist based on team standards. Covers code quality, security, performance, and testing. Use when reviewing pull requests.'
4
---
5

6
## Review Criteria
7

8
### Code Quality
9

10
- [ ] Functions are under 50 lines
11
- [ ] No console.logs in production code
12
- [ ] Meaningful variable names
13
- [ ] Comments explain "why" not "what"
14

15
### Security
16

17
- [ ] No hardcoded credentials
18
- [ ] Input validation on all external data
19
- [ ] Proper error handling without exposing internals
20

21
### Testing
22

23
- [ ] Unit tests for new functions
24
- [ ] Integration tests for API endpoints
25
- [ ] Coverage above 80%

Benefits of Agent Skills

Faster Workflows

Why it’s awesome

Once you’ve got skills set up, you’ll notice how much time you save. No more typing out the same explanations every day. No more copy-pasting from that doc you wrote six months ago. You just ask Copilot, and it already knows what to do.

Complex tasks that used to take multiple back-and-forth conversations? Now they happen in one shot because Copilot has all the context it needs ready to go.

Team Knowledge Sharing

Here’s something cool: skills make institutional knowledge accessible to everyone. That pattern the senior dev uses? That workaround for the weird API quirk? That specific way you want commit messages formatted? Put it in a skill, and now everyone on the team can tap into it.

New team members get up to speed faster because the knowledge is right there in the codebase, not locked away in someone’s head.

Consistent Results

With skills, you get consistency. Copilot follows your established patterns every time. No more “well, last time it suggested this pattern, but today it’s suggesting something different” situations.

Scalable Automation

The real power move is bundling scripts with your instructions. Instead of Copilot just giving you advice, it can actually do things. Run your image optimizer. Generate your boilerplate. Execute your tests. That’s the difference between a helpful suggestion and actual automation.

Quick Reference

Next Steps

Start small and build up

Don’t try to create the perfect skill right away. Start with something simple that solves a task you do all the time. Maybe it’s generating test files in your team’s format, or maybe it’s a checklist for deploying to production.

Get that working first. See how Copilot uses it. Then you can add more complexity: bundle in some scripts, create templates, add multiple workflow stages.

As you build out your skills library, Copilot stops feeling like a generic code autocomplete tool. It starts feeling more like a specialized team member who actually knows your codebase, your patterns, and your team’s preferences.

And the best part? Once you’ve built a skill, it’s there for everyone. Your whole team benefits from the time you spent documenting and automating that pattern.