What Are GitHub Copilot Skills?

What Are GitHub Copilot Skills?

If you have spent any time correcting GitHub Copilot on the same thing twice, skills are the feature you have been reaching for without knowing its name. They are the mechanism for writing down how your team does a particular job once, so Copilot stops guessing at it.

The confusion worth clearing up first is that "skills" in the Copilot world has meant three different things in three years. There were the built-in skills Copilot Chat used to look up a file or search a repository. There were skillsets, part of the Copilot Extensions work. And there are agent skills, which are what people now mean, what GitHub's documentation now describes, and what this guide covers.

Agent skills are also not a GitHub invention. They are an open standard shared across several AI coding tools, which is why a skill written for one agent frequently works in another. That is genuinely useful and it is also the source of most of the muddle in search results, so it is worth being precise about the GitHub-specific parts.

What Is the Short Answer?

A GitHub Copilot skill is a folder containing a file named exactly SKILL.md, holding instructions in Markdown with a short YAML frontmatter block. Copilot reads the frontmatter description, decides on its own whether the skill is relevant to what you have asked, and if it is, injects the file's contents into its context for that task.

Put skills in .github/skills to share them with everyone working in a repository, or in ~/.copilot/skills to keep them to yourself across all your projects. One subdirectory per skill, lowercase with hyphens.

That is the entire mechanism. There is no registration step, no manifest to maintain, and nothing to deploy. You commit a Markdown file and Copilot starts using it.

Not sure which of your pages are actually bringing people in? Start with a free SEO audit and get a clear picture.

Where Do Skill Files Actually Go?

GitHub recognises two scopes, and choosing the wrong one is the most common setup mistake.

Repository skills

These live in the repository and are shared with everyone who clones it. Three locations are recognised:

• .github/skills — the GitHub-native location and the one to default to.
• .claude/skills — recognised because the standard is shared.
• .agents/skills — the vendor-neutral option.

Pick .github/skills unless you already have skills in one of the others, in which case leave them where they are. Copilot reads all three, so there is nothing to gain from moving them and a review to sit through if you do.

Personal skills

These follow you across every project and are never committed:

• ~/.copilot/skills
• ~/.agents/skills

Personal skills are the right home for things that are about you rather than about the code: how you like commit messages phrased, which review comments you want made, the shape of your preferred debugging approach.

The rule of thumb is ownership. If a new team member would need the skill to do the job correctly, it belongs in the repository. If it only reflects your own habits, keep it personal — otherwise you are quietly imposing your preferences on everyone else's Copilot.

What Goes Inside SKILL.md?

The frontmatter has two required fields and two optional ones.

• name (required) — a unique identifier, lowercase with hyphens, normally matching the directory name.
• description (required) — what the skill does and when Copilot should use it.
• license (optional) — the licence covering the skill, which matters if you publish it.
• allowed-tools (optional) — tools Copilot may use without asking first. Anything not listed prompts for permission.

Everything after the frontmatter is ordinary Markdown: instructions, examples, conventions, whatever the job needs.

The description is the part that matters

This is where most skills fail, and it fails silently. Copilot decides whether to load a skill by reading its description against your prompt. A vague description means the skill never loads, and because nothing errors, you conclude skills do not work.

Write the description as a trigger rather than a title. "Testing guidelines" tells Copilot nothing. "Use when writing or modifying Playwright end-to-end tests in this repository; covers fixture setup, selector conventions and the CI retry policy" tells it exactly when to reach for the file.

Treat allowed-tools carefully

Listing shell or bash in allowed-tools removes the confirmation prompt before Copilot runs terminal commands. GitHub's own documentation flags this as risky, and it is worth taking seriously: a skill is a Markdown file, and a Markdown file in a pull request gets far less scrutiny than code. Pre-approve shell access only for skills you wrote or have read line by line.

Ready to see how your site is really performing? Start with a free SEO audit and find out in minutes.

Which Surfaces Support Skills?

This matters because a skill that works for one teammate may appear broken for another using a different client. Skills are supported in:

• The Copilot cloud agent
• Copilot code review
• GitHub Copilot CLI
• The GitHub Copilot app
• Agent mode in Visual Studio Code and in JetBrains IDEs

On availability, the cloud agent comes with all paid Copilot plans and works in repositories on GitHub, excluding those owned by managed user accounts or where it has been disabled. Copilot CLI is available on all Copilot plans, but if your access comes through an organisation, that organisation has to enable the CLI policy first.

One practical note for code review: naming a review-oriented skill directory something like code-review helps ensure it is picked up for reviews. The description still does the work, but the directory name is a useful nudge.

How Do You Build One, Step by Step?

1. Decide the scope. Repository or personal, per the ownership rule above.
2. Create the directory. For example .github/skills/api-error-handling. Lowercase, hyphenated.
3. Write SKILL.md. The filename is exact and case-sensitive. A file called Skill.md or skill.md will be ignored without complaint.
4. Write the description as a trigger. State what the skill covers and the situation in which Copilot should reach for it.
5. Keep the body specific. Your conventions, your error types, your naming, with a short example. Generic best practice is already in the model; what it lacks is how your codebase does things.
6. Add supporting files if useful. Scripts, reference docs and checklists can live in the skill directory and be referenced from SKILL.md. When the skill loads, every file in the directory becomes available.
7. Test by asking a question that should trigger it. If it does not load, the description is almost always the problem, not the body.
8. Commit it and tell your team. A repository skill nobody knows exists will quietly change Copilot's behaviour, which is confusing if it is a surprise.

When Should You Use a Skill, and When Not?

Skills earn their place when the knowledge is procedural and repeatable: a migration you run the same way every time, a test-writing convention, a release checklist, the specific way your service handles errors.

They are the wrong tool for a one-off instruction, which belongs in the prompt. They are also the wrong tool for standing preferences that should apply to everything — those belong in custom instructions, which are always loaded rather than conditionally loaded.

That distinction is the most useful one to hold on to. Custom instructions are context Copilot always has. Skills are context Copilot fetches when it decides the task calls for it. Putting always-relevant rules in a skill means they sometimes do not apply; putting conditional procedures in instructions means burning context on them constantly.

Want to know where you stand against your competitors? Get a free SEO audit and see the gaps.

What Are the Limitations Worth Knowing?

You do not control when a skill loads. Copilot decides, from the description. There is no way to force one on for a task, which means a well-written skill can still be skipped.

Failure is silent. Nothing tells you a skill was considered and rejected. Debugging means rewriting the description and trying again, which is a slow loop.

Surface support is uneven. The list above is real but not universal, and a skill that works in the CLI may not apply in an older editor plugin. Check before concluding it is broken.

Shared skills are unverified code paths. GitHub does not verify published skills. The gh skill command — public preview, requiring GitHub CLI 2.90.0 or later — can search, preview, install and update them, and gh skill preview exists precisely so you read one before installing it. Do.

Markdown gets reviewed less carefully than code. A skill changes how an agent behaves across a repository. That deserves code-level review, and in practice rarely gets it.

They do not add capability. A skill teaches Copilot how you want a job done. It does not give Copilot access it did not have, and it will not rescue a task the model cannot do.

How Do Skills Compare to the Alternatives?

Against custom instructions: instructions are always on, skills are conditional. Use instructions for the handful of rules that apply everywhere, skills for the many procedures that apply sometimes. Most teams need both.

Against MCP servers: not a comparison so much as a division of labour. An MCP server gives Copilot new abilities — reaching a database, an API, an internal service. A skill gives it knowledge. If the gap is "Copilot cannot see X", you need a server; if it is "Copilot does X wrong", you need a skill.

Against prompt files and chat modes: prompt files are reusable prompts you invoke deliberately. Skills are invoked by Copilot on your behalf. Deliberate invocation is more predictable; automatic invocation is less work. For a task you run weekly and remember, a prompt file is fine. For knowledge you want applied whenever it is relevant, a skill is better.

Against a README or contributing guide: documentation is for people and is read inconsistently by both humans and agents. A skill is structured to be loaded on purpose. Many teams end up with the skill as the real source of truth and the guide pointing at it.

Final Thoughts

Agent skills are the least glamorous Copilot feature and probably the highest-leverage one, because they fix the specific failure that makes AI assistance frustrating: being confidently wrong about your codebase in the same way over and over.

The practical advice is to start with one. Pick the correction you have made most often this month, write it down as a skill with a description that says exactly when it applies, and commit it. One good skill changes more about day-to-day Copilot output than a directory of speculative ones, which mostly sit unloaded.

Then resist building a library. Skills are cheap to write and invisible when they fail, which is a combination that produces a lot of files nobody can account for. Add the second only once the first has demonstrably earned it. If you are still setting up the basics, our guide to how to use GitHub Copilot covers the modes and plans underneath all of this.

Ready to find out what your whole digital setup looks like from the outside? Start with a free SEO audit and get a clear picture.