Based on GitHub / Microsoft’s official docs, checked November 2, 2026

GitHub Copilot skills: create, install and use agent skills

Agent skills are how you give GitHub Copilot a repeatable workflow. A skill is a folder with a SKILL.md file of instructions, plus optional scripts and other resources. Copilot loads a skill when your task matches its description, instead of carrying the whole workflow in every conversation. GitHub says skills follow the open Agent Skills specification, so the same folder format is used by other agents too. Skills work in the GitHub Copilot app, Copilot CLI, Copilot cloud agent and Copilot code review on GitHub.com, and agent mode in VS Code, Visual Studio and JetBrains IDEs (IDE support depends on the version). This guide covers where Copilot looks for skills, how to write one, how to call and manage skills in Copilot CLI, and how to install other people’s skills with gh skill. Everything here comes from GitHub’s Copilot documentation, checked November 2, 2026.

1. 1. Create a skills directory

   For a project skill, create .github/skills, .claude/skills or .agents/skills in your repository. For a personal skill shared across projects, create ~/.copilot/skills or ~/.agents/skills in your home directory.

   mkdir -p .github/skills/github-actions-failure-debugging

2. 2. Write SKILL.md

   Each skill gets its own subdirectory, named in lowercase with hyphens. The file must be called SKILL.md, with YAML frontmatter: name (required, lowercase with hyphens, usually the directory name), description (required: what the skill does and when Copilot should use it) and an optional license. The Markdown body holds the instructions.

   ---
   name: github-actions-failure-debugging
   description: Guide for debugging failing GitHub Actions workflows. Use this when asked to debug failing GitHub Actions workflows.
   ---
   
   To debug failing GitHub Actions workflows in a pull request:
   1. Look up recent workflow runs for the pull request and their status.
   2. Summarize the logs of the failed jobs.
   3. Reproduce the failure, fix it and confirm the fix.

3. 3. Load it in Copilot CLI

   Start a new CLI session, or run /skills reload in the current one. Then check it with /skills info and the skill name.

   /skills reload
   /skills info github-actions-failure-debugging

4. 4. Use the skill

   Copilot decides when to use a skill from your prompt and the skill’s description. To ask for a specific one, put its name after a forward slash in your prompt.

   Use the /github-actions-failure-debugging skill to find out why CI failed on this PR.

Where Copilot looks for skills

Project skills live in the repository, in .github/skills, .claude/skills or .agents/skills. Personal skills live in ~/.copilot/skills or ~/.agents/skills.

Because .claude/skills and .agents/skills are on the list, a skill folder you already use with Claude Code or another agent can work in Copilot without moving it.

Supported locations depend on the surface. GitHub warns not to assume a personal skill is available to an agent running in the cloud. To make personal skills available in cloud sandbox sessions, put them in .copilot/skills in your dotfiles repository; that does not apply to GitHub Actions-based sessions.

Skills with scripts

When a skill is invoked, Copilot discovers every file in the skill’s directory and makes it available with the instructions, so a skill can ship a script and tell Copilot when to run it.

The allowed-tools frontmatter field lists tools Copilot may use without asking each time; anything not listed still needs your permission. GitHub warns to pre-approve shell or bash only for skills and scripts you have reviewed and fully trust, because it removes the confirmation step for terminal commands.

---
name: image-convert
description: Converts SVG images to PNG format. Use when asked to convert SVG files.
allowed-tools: shell
---

When asked to convert an SVG to PNG, run convert-svg-to-png.sh from this skill's base directory, passing the input SVG file path as the first argument.

Managing skills in Copilot CLI

/skills list shows the available skills (or just ask Copilot what skills it has). /skills opens a picker where you can enable or disable a skill. /skills info shows details, including the skill’s location. /skills add adds another skills location, /skills reload picks up new skills without restarting, and /skills remove removes a skill you added directly. Skills that came with a plugin are managed through the plugin.

The same operations work outside a session with the copilot skill subcommand, for example copilot skill list, copilot skill add, copilot skill disable and copilot skill enable.

Installing skills with gh skill

GitHub CLI 2.90.0 or later has gh skill, in public preview, to search, preview, install, update and publish skills from GitHub repositories. GitHub warns that skills are not verified and may contain prompt injections, hidden instructions or malicious scripts, so preview a skill before installing it.

You can install a specific version with @TAG or @SHA, or lock one with --pin so updates skip it; the two can’t be combined. You can also download a skill folder by hand, for example from the Awesome GitHub Copilot collection or the anthropics/skills repository, and move it into one of the skill locations.

gh skill search TOPIC
gh skill preview OWNER/REPOSITORY SKILL
gh skill install github/awesome-copilot documentation-writer
gh skill install github/awesome-copilot documentation-writer --pin v1.2.0

Skills or custom instructions?

GitHub recommends custom instructions for short guidance that applies to almost every task, such as your coding standards, and skills for detailed instructions Copilot should only load when relevant.

Tips

• Write the description so it says exactly when the skill should be used; that is what Copilot matches your prompt against.
• Keep shared skills in .github/skills in the repository so everyone on the team gets them.
• Run gh skill preview before every install and read any scripts the skill ships.
• Leave shell and bash out of allowed-tools unless you wrote or fully reviewed the skill.

Next steps

Sources

• https://docs.github.com/en/copilot/concepts/agents/about-agent-skills · checked 2026-11-02
• https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills · checked 2026-11-02
• https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills · checked 2026-11-02