---
title: "Setting Up GitHub Copilot Agent Skills in Your Repository"
lang: "en"
author: "Mohammad Abu Mattar"
canonical: https://mkabumattar.com/post/github-copilot-agent-skills-setup
---

![Blog post image for Setting Up GitHub Copilot Agent Skills in Your Repository - How to build custom Agent Skills for GitHub Copilot on the agentskills.io open standard: folder structure, SKILL.md configuration, the progressive-disclosure loading model, and enabling the feature in VS Code.](/_astro/hero.CCW95PMK_Z107rgh.webp)

[Home](/)›[Devtips](/devtips)›[All Categories](/devtips/categories)›[Developer Tools & Productivity](/devtips/categories/developer-tools--productivity)

Devtips

[Developer Tools & Productivity](/devtips/categories/developer-tools--productivity)

# Setting Up GitHub Copilot Agent Skills in Your Repository

[Mohammad Abu Mattar](/authors/mohammad-abu-mattar)Published: 26 Jan 202606 Mins read09 Mins listen

[Markdown for AI(opens in a new tab)](/post/github-copilot-agent-skills-setup/index.md "Open the plain-Markdown version of this page, for pasting into an AI tool")

TL;DR

How to build custom Agent Skills for GitHub Copilot on the agentskills.io open standard: folder structure, SKILL.md configuration, the progressive-disclosure loading model, and enabling the feature in VS Code.

Series

[AI & LLM Engineering](/series/ai--llm-engineering)1/1

All posts in this series (1)

DevTips1

1.  [Setting Up GitHub Copilot Agent Skills in Your RepositoryYou are here](/devtips/post/github-copilot-agent-skills-setup)

### Setting Up GitHub Copilot Agent Skills in Your Repository

Contents

[Why teach Copilot new skills?](#why-teach-copilot-new-skills)[What a skill actually is](#what-a-skill-actually-is)[Loading only what's needed](#loading-only-whats-needed)[The problem: generic AI responses](#the-problem-generic-ai-responses)[One-size-fits-all answers](#one-size-fits-all-answers)[Context overload](#context-overload)[Repeating yourself](#repeating-yourself)[The fix: repository-based Agent Skills](#the-fix-repository-based-agent-skills)[How Agent Skills are organized](#how-agent-skills-are-organized)[The three-level loading system (progressive disclosure)](#the-three-level-loading-system-progressive-disclosure)[Knowledge that stays put](#knowledge-that-stays-put)[Setting up your first skill](#setting-up-your-first-skill)[Step 1: create the skills directory](#step-1-create-the-skills-directory)[Step 2: write the SKILL.md file](#step-2-write-the-skillmd-file)[Step 3: add scripts and resources](#step-3-add-scripts-and-resources)[Tools Available](#tools-available)[Step 4: enable skills in VS Code](#step-4-enable-skills-in-vs-code)[Skill examples](#skill-examples)[Documentation generator](#documentation-generator)[Documentation Format](#documentation-format)[Test suite builder](#test-suite-builder)[Test Structure](#test-structure)[Code review checklist](#code-review-checklist)[Review Criteria](#review-criteria)[Code Quality](#code-quality)[Security](#security)[Testing](#testing)[What you get out of it](#what-you-get-out-of-it)[Less repetition](#less-repetition)[Knowledge the whole team can use](#knowledge-the-whole-team-can-use)[Consistent output](#consistent-output)[Automation, not just advice](#automation-not-just-advice)[Quick Reference](#quick-reference)[Next steps](#next-steps)

## [Why teach Copilot new skills?](#why-teach-copilot-new-skills)

### [What a skill actually is](#what-a-skill-actually-is)

If you’re ready to teach Copilot some new tricks, Agent Skills are your answer. Built on the [agentskills.io](https://agentskills.io) open standard, a skill is a folder of instructions and tools that Copilot only opens when it’s relevant to what you’re working on. It’s an assistant who knows which reference book to grab off the shelf, instead of one who dumps the whole library on the desk every time.

### [Loading only what’s needed](#loading-only-whats-needed)

Loading everything at once would slow Copilot down and fill its context with things that don’t apply to the file you’re in. Agent Skills use **progressive disclosure** to pull in targeted context only when it matters, so responses stay fast and stay on topic.

## [The problem: generic AI responses](#the-problem-generic-ai-responses)

### [One-size-fits-all answers](#one-size-fits-all-answers)

Out of the box, Copilot is helpful but generic. It doesn’t know your team’s workflows, your project’s naming conventions, or the specialized tasks you run every week. So you type the same explanations over and over, session after session.

### [Context overload](#context-overload)

Explaining everything upfront causes two problems. It slows every response down. And Copilot’s answers get muddier, because the signal you care about is buried in the context you pasted.

### [Repeating yourself](#repeating-yourself)

Without skills, every new coding session starts from zero. You re-explain the same project patterns, and the explaining never turns into anything you can reuse.

## [The fix: repository-based Agent Skills](#the-fix-repository-based-agent-skills)

### [How Agent Skills are organized](#how-agent-skills-are-organized)

Agent Skills are folders that live in your repo, or in your user profile. They hold instructions, scripts and tools that Copilot can reach for when needed. The format is portable across agents, including GitHub Copilot in VS Code, the CLI and the coding agent.

### [The three-level loading system (progressive disclosure)](#the-three-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.

### [Knowledge that stays put](#knowledge-that-stays-put)

Skills live in your repository, so the `.github/skills` directory travels with a clone and shows up in code review like any other change. Nobody has to configure anything to get them.

## [Setting up your first skill](#setting-up-your-first-skill)

### [Step 1: create the skills directory](#step-1-create-the-skills-directory)

First, pick where your skills folder lives. Recommended locations:

-   **Project skills**: `.github/skills/` (recommended) or `.claude/skills/` (for backward compatibility).
-   **Personal skills**: `~/.copilot/skills/` (recommended) or `~/.claude/skills/`.

Say you pick `.github/skills`. Here’s how you’d set it up:

Terminal window

```
# Create the main skills directorymkdir -p .github/skills
# Create a specific skill foldermkdir .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](#step-2-write-the-skillmd-file)

Every skill needs a `SKILL.md` file (uppercase) with YAML frontmatter at the top. Spend your time on the `description`, because that is the only text level 1 discovery sees when it decides whether to load the skill at all.

Here’s a real example:

.github/skills/image-resizer/SKILL.md

```
1---2name: 'Image Resizer'3description: '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 Workflow7
8First, I'll check what you're starting with:9
10- Look at source image dimensions and format11- Figure out what target sizes you need12- Make sure the output directory exists13
14Next, I'll handle the actual work using the [optimization script](./scripts/optimize.js).15
16Finally, I'll verify the output quality and file sizes.
```

Notice how the description names concrete things: batch processing, aspect ratios, responsive sets. That specificity is what makes Copilot pick the skill up when you mention images or resizing.

### [Step 3: add scripts and resources](#step-3-add-scripts-and-resources)

This is where skills get more useful than a prompt file. You’re not limited to instructions. You can bundle JavaScript scripts, templates and configuration files alongside your `SKILL.md`, then reference them with relative paths.

Here’s what your folder structure might look like:

Terminal window

```
.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:

.github/skills/image-resizer/SKILL.md

```
1## Tools Available2
3To resize images, run: `./scripts/resize-images.js`4
5For optimization, use: `./scripts/optimize.js`6
7Configuration template: `./templates/config-template.json`
```

Now when you ask Copilot to resize images, it points at the script that already exists and has been tested, instead of writing you a fresh one that has not.

### [Step 4: enable skills in VS Code](#step-4-enable-skills-in-vs-code)

This feature is currently in preview, so you’ll need 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:

.vscode/settings.json

```
1{2  "chat.useAgentSkills": true3}
```

  

Worth knowing

Copilot’s “Agent Mode” (Windows & Linux: `Ctrl+I`, Mac: `Cmd+I`) is highly optimized for using these skills autonomously. For the best experience, try invoking Copilot in Agent Mode when working with your custom skills.

Once it’s enabled, test it. Open Copilot chat and ask “What skills do you have?” If the wiring is right, Copilot lists your new skill and summarises what it does. If it doesn’t, your frontmatter is usually the problem.

## [Skill examples](#skill-examples)

### [Documentation generator](#documentation-generator)

Say your team has a style guide for docs. A skill can hold those conventions so generated documentation comes out in your format rather than a generic one.

.github/skills/doc-generator/SKILL.md

```
1---2name: 'Documentation Generator'3description: "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 Format7
8Each function should include:9
101. Brief description (one sentence)112. Parameter table with types and descriptions123. Return value explanation134. Code example showing typical usage145. Common gotchas or edge cases15
16Example template is in `./templates/api-doc.md`
```

### [Test suite builder](#test-suite-builder)

Tired of writing the same boilerplate test code? Build a skill that knows your testing patterns and can scaffold a whole suite.

.github/skills/test-builder/SKILL.md

```
1---2name: 'Test Suite Builder'3description: '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 Structure7
8For each component/function, generate:9
10- Setup and teardown blocks11- Happy path tests12- Edge case coverage13- Error handling tests14- Mock setup when needed15
16Refer to `./examples/sample-test.spec.ts` for the pattern.
```

### [Code review checklist](#code-review-checklist)

Your team’s review standards can go into a skill too, so the checklist runs on the PR instead of living in a wiki page nobody opens.

.github/skills/code-review/SKILL.md

```
1---2name: 'Code Review Checklist'3description: '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 Criteria7
8### Code Quality9
10- [ ] Functions are under 50 lines11- [ ] No console.logs in production code12- [ ] Meaningful variable names13- [ ] Comments explain "why" not "what"14
15### Security16
17- [ ] No hardcoded credentials18- [ ] Input validation on all external data19- [ ] Proper error handling without exposing internals20
21### Testing22
23- [ ] Unit tests for new functions24- [ ] Integration tests for API endpoints25- [ ] Coverage above 80%
```

## [What you get out of it](#what-you-get-out-of-it)

### [Less repetition](#less-repetition)

The saving shows up in the explaining you stop doing. No typing out the same conventions every morning, no digging up the doc you wrote six months ago to paste into chat.

Tasks that used to take three or four rounds of correction land closer to first try, because the context Copilot needed was already loaded.

### [Knowledge the whole team can use](#knowledge-the-whole-team-can-use)

Skills move institutional knowledge out of people’s heads. The pattern the senior dev always uses, the workaround for that one API quirk, the commit message format you keep correcting in review: put it in a skill and it applies to everyone.

New hires come up to speed faster because the knowledge is in the repo they just cloned.

### [Consistent output](#consistent-output)

Copilot follows the same patterns each time, so you stop getting one suggestion today and a different one tomorrow for the same kind of change.

### [Automation, not just advice](#automation-not-just-advice)

Bundling scripts with the instructions is the part I’d not give up. Copilot can run your image optimizer, generate the boilerplate, execute the tests. Advice you have to implement and a script that already works are not in the same category.

## [Quick Reference](#quick-reference)

1.  **Create Skills Directory**: Choose a location (`.github/skills/`, `.copilot/skills/`, or `.claude/skills/`) and create a subfolder for your skill.
    
      
    
    Terminal window
    
    ```
    mkdir -p .github/skills/my-skill
    ```
    
2.  **Create SKILL.md**: Inside your skill folder, create a `SKILL.md` file with YAML frontmatter including `name` and `description`.
    
      
    
    .github/skills/my-skill/SKILL.md
    
    ```
    1---2name: 'My Skill'3description: 'Brief description of what this skill does and when to use it.'4---
    ```
    
3.  **Add Resources**: Include any scripts, templates, or additional files your skill needs in the same folder.
    
      
    
    Terminal window
    
    ```
    mkdir .github/skills/my-skill/scripts
    ```
    
4.  **Reference Assets**: Use relative paths in `SKILL.md` to point to your scripts or templates.
    
      
    
    .github/skills/my-skill/SKILL.md
    
    ```
    1To run the script, use: `./scripts/my-script.js`
    ```
    
5.  **Enable in VS Code**: Turn on Agent Skills in VS Code settings by enabling `chat.useAgentSkills`.
    
      
    
    .vscode/settings.json
    
    ```
    1{2  "chat.useAgentSkills": true3}
    ```
    
6.  **Verify Setup**: Open Copilot Chat and ask, “What skills do you have?” to confirm your skill is recognized.
    

## [Next steps](#next-steps)

Don’t try to write the perfect skill first. Start with one small task you do constantly. Generating test files in your team’s format, say, or the checklist you run before a production deploy.

Get that working. Watch how Copilot uses it, because the first description you write is usually too vague to trigger reliably. Then add scripts and templates once the plain version earns its place.

As the library grows, Copilot stops behaving like autocomplete and starts behaving like someone who has read your codebase.

The write-up is a one-time cost, and the skill stays in the repo for whoever clones it next.

Was this useful?

## Tags

[#GitHub Copilot](/devtips/tags/github-copilot)[#AI Tools](/devtips/tags/ai-tools)[#VS Code](/devtips/tags/vs-code)[#Developer Productivity](/devtips/tags/developer-productivity)[#AI Agents](/devtips/tags/ai-agents)[#Automation](/devtips/tags/automation)[#IDE Extensions](/devtips/tags/ide-extensions)

## Share

[Facebook](https://facebook.com/sharer/sharer.php?u=https%3A%2F%2Fmkabumattar.com%2Fdevtips%2Fpost%2Fgithub-copilot-agent-skills-setup "Share on Facebook")[Twitter](https://twitter.com/intent/tweet/?text=Setting%20Up%20GitHub%20Copilot%20Agent%20Skills%20in%20Your%20Repository&url=https%3A%2F%2Fmkabumattar.com%2Fdevtips%2Fpost%2Fgithub-copilot-agent-skills-setup "Share on Twitter")[LinkedIn](https://www.linkedin.com/shareArticle?mini=true&url=https%3A%2F%2Fmkabumattar.com%2Fdevtips%2Fpost%2Fgithub-copilot-agent-skills-setup&title=Setting%20Up%20GitHub%20Copilot%20Agent%20Skills%20in%20Your%20Repository&summary=How%20to%20build%20custom%20Agent%20Skills%20for%20GitHub%20Copilot%20on%20the%20agentskills.io%20open%20standard%3A%20folder%20structure%2C%20SKILL.md%20configuration%2C%20the%20progressive-disclosure%20loading%20model%2C%20and%20enabling%20the%20feature%20in%20VS%20Code.&source=https://mkabumattar.com "Share on LinkedIn")[WhatsApp](https://wa.me/?text=Setting%20Up%20GitHub%20Copilot%20Agent%20Skills%20in%20Your%20Repository%20https%3A%2F%2Fmkabumattar.com%2Fdevtips%2Fpost%2Fgithub-copilot-agent-skills-setup "Share on WhatsApp")[Telegram](https://t.me/share/url?url=https%3A%2F%2Fmkabumattar.com%2Fdevtips%2Fpost%2Fgithub-copilot-agent-skills-setup&text=Setting%20Up%20GitHub%20Copilot%20Agent%20Skills%20in%20Your%20Repository "Share on Telegram")[Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fmkabumattar.com%2Fdevtips%2Fpost%2Fgithub-copilot-agent-skills-setup&title=Setting%20Up%20GitHub%20Copilot%20Agent%20Skills%20in%20Your%20Repository "Share on Reddit")[Hacker News](http://news.ycombinator.com/submitlink?u=https%3A%2F%2Fmkabumattar.com%2Fdevtips%2Fpost%2Fgithub-copilot-agent-skills-setup&t=Setting%20Up%20GitHub%20Copilot%20Agent%20Skills%20in%20Your%20Repository "Share on Hacker News")[Pinterest](https://pinterest.com/pin/create/button/?url=https%3A%2F%2Fmkabumattar.com%2Fdevtips%2Fpost%2Fgithub-copilot-agent-skills-setup&media=&description=How%20to%20build%20custom%20Agent%20Skills%20for%20GitHub%20Copilot%20on%20the%20agentskills.io%20open%20standard%3A%20folder%20structure%2C%20SKILL.md%20configuration%2C%20the%20progressive-disclosure%20loading%20model%2C%20and%20enabling%20the%20feature%20in%20VS%20Code. "Share on Pinterest")[Email](<mailto:?subject=Setting%20Up%20GitHub%20Copilot%20Agent%20Skills%20in%20Your%20Repository&body=Check out this article: https%3A%2F%2Fmkabumattar.com%2Fdevtips%2Fpost%2Fgithub-copilot-agent-skills-setup>)

## Comments

## You might also enjoy

More posts on similar topics

[![Docker Is Eating Your Disk Space (And How PruneMate Fixes It)](/_astro/hero.BD8-gtdG_26qrXW.webp)](/devtips/post/docker-disk-space-prunemate)

## [Docker Is Eating Your Disk Space (And How PruneMate Fixes It)](/devtips/post/docker-disk-space-prunemate)

-   [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)
-   [Containers & Docker](/devtips/categories/containers--docker)

The problem: Docker is eating your disk space What it looks like when it happens Your Docker host is running out of space. Again. You've been spinning up containers, testing new services

[#Docker](/devtips/tags/docker)[#Containers](/devtips/tags/containers)[#Home Lab](/devtips/tags/home-lab)+5 tags

[read more](/devtips/post/docker-disk-space-prunemate)

[![Container Image Vulnerability Scanning in CI/CD with Trivy](/_astro/hero.yY1orHlw_2oq3jw.webp)](/devtips/post/container-image-vulnerability-scanning-trivy)

## [Container Image Vulnerability Scanning in CI/CD with Trivy](/devtips/post/container-image-vulnerability-scanning-trivy)

-   [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)
-   [DevOps & DevSecOps](/devtips/categories/devops--devsecops)

Why container security matters Where the vulnerabilities hide A container image is one of the largest pieces of untrusted code you ship. Every image you build carries the base OS layer,

[#Container Security](/devtips/tags/container-security)[#Vulnerability Scanning](/devtips/tags/vulnerability-scanning)[#Trivy](/devtips/tags/trivy)+4 tags

[read more](/devtips/post/container-image-vulnerability-scanning-trivy)

[![7 Reasons Learning the Linux Terminal is Worth It (Even for Beginners)](/_astro/hero.Ci9C_A6W_1AKnQ0.webp)](/devtips/post/7-reasons-learning-linux-terminal-worth-it-beginners)

## [7 Reasons Learning the Linux Terminal is Worth It (Even for Beginners)](/devtips/post/7-reasons-learning-linux-terminal-worth-it-beginners)

-   [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)
-   [DevOps & DevSecOps](/devtips/categories/devops--devsecops)

Why learn the Linux terminal? Why it still matters Even with the graphical tools and AI assistants available now, the terminal is the most direct way to work with a Linux system. It's a core

[#Linux](/devtips/tags/linux)[#Terminal](/devtips/tags/terminal)[#Command Line](/devtips/tags/command-line)+4 tags

[read more](/devtips/post/7-reasons-learning-linux-terminal-worth-it-beginners)

[![Policy-as-Code Governance with OPA/Rego](/_astro/hero.CwAJ64Mi_1WeH9p.webp)](/devtips/post/policy-as-code-opa-rego)

## [Policy-as-Code Governance with OPA/Rego](/devtips/post/policy-as-code-opa-rego)

-   [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)
-   [DevOps & DevSecOps](/devtips/categories/devops--devsecops)

Why policy-as-code matters The governance problem Managing infrastructure at scale gets complicated fast. As your infrastructure grows, keeping it consistent and compliant gets harder. M

[#Policy as Code](/devtips/tags/policy-as-code)[#OPA/Rego](/devtips/tags/oparego)[#Compliance](/devtips/tags/compliance)+4 tags

[read more](/devtips/post/policy-as-code-opa-rego)

[![Understanding Kubernetes Services: ClusterIP vs NodePort vs LoadBalancer](/_astro/hero.DBNjupL__148EQW.webp)](/devtips/post/kubernetes-services-clusterip-nodeport-loadbalancer)

## [Understanding Kubernetes Services: ClusterIP vs NodePort vs LoadBalancer](/devtips/post/kubernetes-services-clusterip-nodeport-loadbalancer)

-   [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)
-   [DevOps & Kubernetes](/devtips/categories/devops--kubernetes)

If you're working with Kubernetes, you've probably noticed that Pods come and go, and their IP addresses keep changing. That's where Services come in. They give you a stable way to keep your apps acce

[#Kubernetes](/devtips/tags/kubernetes)[#K8s Services](/devtips/tags/k8s-services)[#ClusterIP](/devtips/tags/clusterip)+5 tags

[read more](/devtips/post/kubernetes-services-clusterip-nodeport-loadbalancer)

[![Managing Terraform at Scale with Terragrunt](/_astro/hero.DUZZoi07_ZRPUOh.webp)](/devtips/post/terraform-terragrunt-wrappers)

## [Managing Terraform at Scale with Terragrunt](/devtips/post/terraform-terragrunt-wrappers)

-   [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)
-   [Cloud & Infrastructure Automation](/devtips/categories/cloud--infrastructure-automation)

The problem with Terraform at scale Duplicated code across environments If you're managing infrastructure with Terraform across several environments or projects, you've probably hit the point

[#Terraform](/devtips/tags/terraform)[#Terragrunt](/devtips/tags/terragrunt)[#Infrastructure as Code](/devtips/tags/infrastructure-as-code)+4 tags

[read more](/devtips/post/terraform-terragrunt-wrappers)

6 related posts