What are GitHub Copilot skills?
GitHub Copilot skills are folders with a SKILL.md file that Copilot loads when your prompt matches the skill’s description. Put a project skill in .github/skills, .claude/skills or .agents/skills, or a personal skill in ~/.copilot/skills or ~/.agents/skills. You can install from GitHub with the gh skill command or with npx skills add owner/repo -a github-copilot.
GitHub’s docs separate skills from custom instructions. Instructions suit guidance that applies to nearly every task, while a skill holds detailed guidance Copilot reads only when it is relevant. Of the 195 repositories we reviewed, 47 say they support Copilot.
Where Copilot agent skills work
According to GitHub’s documentation, skills are supported in the GitHub Copilot app, Copilot CLI, the Copilot cloud agent and Copilot code review on GitHub.com, and agent mode in Visual Studio Code, Visual Studio and JetBrains IDEs. IDE support depends on the version, so check the feature matrix for yours.
Personal skills deserve a warning. For cloud sandbox sessions, they have to live in .copilot/skills in your dotfiles repository, and that does not apply to GitHub Actions-based sessions. A skill that works in your terminal may not reach the cloud agent.
Writing a Copilot SKILL.md
Per the guide to adding agent skills, each skill gets its own subdirectory with lowercase, hyphenated names, such as .github/skills/webapp-testing, and the file must be named SKILL.md. The frontmatter has:
name(required), a unique lowercase identifier that usually matches the folderdescription(required), saying what the skill does and when Copilot should use itlicense(optional)allowed-tools(optional), the tools Copilot may use without asking each time
Copilot decides whether to use a skill from your prompt and the description. When it does, the SKILL.md content is injected into the agent’s context, and bundled scripts and examples become available. Put scripts in the skill folder and reference them from SKILL.md.
Which folder to use
Use .github/skills when the repository is Copilot-only. If the same repo also serves Claude Code or another agent, .claude/skills or .agents/skills is the better home, because Copilot reads those too and you keep one copy instead of two. For skills you want in every project, use ~/.copilot/skills or ~/.agents/skills. Remember the cloud-agent caveat above before relying on a personal skill there.
Installing Copilot skills with gh skill
The GitHub CLI has a gh skill command, in public preview and requiring GitHub CLI 2.90.0 or later:
gh skill search TOPIC
gh skill preview OWNER/REPOSITORY SKILL
gh skill install OWNER/REPOSITORY SKILL
gh skill install github/awesome-copilot documentation-writer --pin v1.2.0
gh skill update --allpreview shows a skill before you install it, and that is the step worth keeping. A pinned skill is skipped during updates; to move it, reinstall with a new --pin value. Maintainers can check a repo with gh skill publish --dry-run.
The skills CLI works as well. npx skills add owner/repo -a github-copilot writes to .agents/skills/ in the project, or ~/.copilot/skills/ with -g. Both are on Copilot’s list of supported folders.
A worked example from GitHub’s docs
GitHub’s own example is a project skill at .github/skills/github-actions-failure-debugging/SKILL.md. The frontmatter gives it a name and a description about debugging failing GitHub Actions workflows. The body tells Copilot which steps to follow and which GitHub MCP server tools to call, including list_workflow_runs, summarize_job_log_failures and get_job_logs. The skill adds no new tools of its own. It tells Copilot how to use tools that already exist, which is the usual split between skills and MCP servers. Our guide to skills versus MCP covers it in more depth.
Because project skills live in the repository, committing .github/skills gives everyone who clones the repo the same skills. For Copilot code review, GitHub notes that a directory name like code-review helps make sure the skill is read.
Security: what GitHub says
GitHub’s docs state that skills are not verified by GitHub and may contain prompt injections, hidden instructions or malicious scripts. They tell you to inspect a skill before installing it.
The allowed-tools field needs the most care. Pre-approving shell or bash removes the confirmation step for terminal commands. GitHub’s advice is to do it only for skills you have reviewed and trust, and otherwise leave the field out so Copilot asks first. When we review a skill, a pre-approved shell is one of the things we flag, because it turns a text file into something that can run commands without a prompt.
Which Copilot skills are worth a look
Among the 47 repositories that list Copilot, none came out clean in our review: 30 are marked “review before installing” and 17 “broad access”. Two examples:
- github/awesome-copilot is the GitHub-run community collection, with 466 skills we count. It is active and useful, but contributions are third-party and uneven. We could review only a fraction of its files. Pick individual skills and read them. Verdict: install with caveats.
- microsoft/azure-skills is official and well maintained, but its scripts run
az,azdandkubectlagainst your own subscription and some steps create resources. Use a least-privilege Azure identity. Marked “broad access”.
See our methodology for how the statuses work and the security page for the install checklist. The skills directory holds every review, and the list of packs below is filtered to repositories that mention Copilot.