GitHub Copilot agent skills: SKILL.md folders, locations and gh skill

GitHub Copilot agent skills are folders that teach Copilot a specific, repeatable task: each one holds a SKILL.md file with instructions, plus any scripts or examples it needs, and Copilot loads it only when your request matches the skill's description. You put project skills in .github/skills, .claude/skills or .agents/skills in your repo, or personal skills in ~/.copilot/skills.

GitHub defines them as "folders of instructions, scripts, and resources that Copilot can load when relevant to improve its performance in specialized tasks." This guide is based on GitHub's agent skills documentation read on 24 October 2026.

What are Copilot agent skills?

Skills follow the Agent Skills specification, which GitHub calls "an open standard, used by a range of different AI systems." So a skill folder you write for Copilot can also work in other tools that support the standard. For the format in general, see the Agent Skills guide.

GitHub's example: a release notes skill can bundle your team's template, a script for gathering changes and instructions for grouping them. "The agent loads those resources when working on release notes, rather than including the whole workflow in every conversation." That is the point of skills: detailed know-how without bloating every prompt.

Which Copilot surfaces use skills?

GitHub lists these places:

• The GitHub Copilot app
• Copilot CLI
• Copilot cloud agent and Copilot code review on GitHub.com
• Agent mode in VS Code, Visual Studio and JetBrains IDEs

GitHub's customization cheat sheet gives the per-IDE detail:

GitHub's pages don't fully agree: the how-to on adding skills names only agent mode in VS Code among the IDEs. IDE support also depends on the version you run, so check the feature matrix and keep your editor and the Copilot extension up to date.

Where do you put skill folders?

Copilot reads two kinds of skills:

Each skill gets its own subfolder, named in lowercase with hyphens, for example .github/skills/webapp-testing. GitHub adds a warning worth taking seriously: "Supported locations depend on the surface." GitHub advises against assuming a personal skill on your machine is available to an agent running in the cloud, so anything the whole team relies on belongs in the repo.

How do you write a SKILL.md for Copilot?

The file must be named exactly SKILL.md. It has YAML frontmatter and a Markdown body. Per GitHub's how-to on adding skills, the fields are:

• name (required): a unique identifier, lowercase with hyphens, usually matching the folder name.
• description (required): what the skill does and when Copilot should use it.
• license (optional): the license that applies to the skill.

Here is GitHub's own example, which lives at .github/skills/github-actions-failure-debugging/SKILL.md:

---
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, follow this process, using tools provided from the GitHub MCP Server:

1. Use the `list_workflow_runs` tool to look up recent workflow runs for the pull request and their status
2. Use the `summarize_job_log_failures` tool to get an AI summary of the logs for failed jobs, to understand what went wrong without filling your context windows with thousands of lines of logs
3. If you still need more information, use the `get_job_logs` or `get_workflow_run_logs` tool to get the full, detailed failure logs
4. Try to reproduce the failure yourself in your own environment.
5. Fix the failing build. If you were able to reproduce the failure yourself, make sure it is fixed before committing your changes.

The description does most of the work. GitHub says Copilot "will decide when to use your skills based on your prompt and the skill's description," so say plainly what the skill is for and the phrases that should trigger it. If you are starting from a prompt you already use, Kipt's free SKILL.md generator turns it into a skill in the browser and checks the name and description limits.

How do skills run scripts?

When a skill is invoked, Copilot "automatically discovers all of the files in the skill's directory and makes them available alongside the skill's instructions." So you can ship a script next to SKILL.md:

.github/skills/image-convert/
├── SKILL.md
└── convert-svg-to-png.sh

Then tell Copilot in the body when and how to run it. You can also pre-approve tools with an allowed-tools field in the frontmatter:

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

Tools not listed there still need your confirmation. GitHub warns to "only pre-approve the shell or bash tools if you have reviewed this skill and any referenced scripts, and you fully trust their source," because doing so removes the confirmation step for terminal commands.

How do you install skills with gh skill?

The GitHub CLI has a gh skill command for discovering, installing, updating and publishing skills. It is in public preview and needs GitHub CLI 2.90.0 or later.

# find skills on a topic
gh skill search TOPIC

# inspect a skill's SKILL.md and files without installing
gh skill preview OWNER/REPOSITORY SKILL

# install one skill (project scope, for Copilot, by default)
gh skill install github/awesome-copilot documentation-writer

# pin a version so updates skip it
gh skill install github/awesome-copilot documentation-writer --pin v1.2.0

# check installed skills for upstream changes
gh skill update --all

Install also accepts --agent and --scope, for example --agent claude-code --scope user. When gh skill installs a skill it writes provenance (source repo, ref and tree SHA) into the frontmatter, which is how gh skill update knows where to look. Maintainers can validate against the spec with gh skill publish --dry-run. The full reference is in the gh skill manual.

GitHub's warning applies to every shared skill: "Skills are not verified by GitHub and may contain prompt injections, hidden instructions, or malicious scripts." Always preview first. Good sources GitHub names are github/awesome-copilot and anthropics/skills. You can also download a skill folder by hand and move it into one of the locations above.

How do you use and manage skills in Copilot CLI?

Copilot picks skills automatically, but in Copilot CLI you can also name one with a slash, for example Use the /frontend-design skill to create a responsive navigation bar in React. Useful commands:

• /skills list shows available skills.
• /skills info SKILL-NAME shows details, including its location.
• /skills reload picks up a skill added mid-session.
• /skills lets you enable or disable a skill.
• copilot skill list, copilot skill add and copilot skill disable do the same from the shell, handy for scripts.

For code review on GitHub.com, GitHub suggests a review-focused folder name such as code-review so the reviewer reliably picks the skill up.

Skills or custom instructions?

GitHub's guidance is short: use custom instructions "for simple instructions relevant to almost every task" and skills "for more detailed instructions that Copilot should only access when relevant." Coding standards go in .github/copilot-instructions.md (see the custom instructions guide); a ten-step release process goes in a skill.

Keep one copy of your skills

Because Copilot reads the open Agent Skills format, one set of skill folders can serve several tools. Kipt stores your prompts and Agent Skills as Markdown in a private GitHub repo you own, imports skills from a GitHub link, folder or .zip, and installs them into Claude Code or Codex with one command. For the other tools, see Codex skills and Cursor skills.