Home › Rules › GitHub Copilot skills

GitHub Copilot skills: folder, SKILL.md, gh skill and examples

From GitHub's own Copilot docs (About agent skills, Adding agent skills, Comparing customizations) and the GitHub CLI gh skill manual, checked Nov 7, 2026. Sources below.

• Guide
• GitHub Copilot
• Skills
• SKILL.md
• gh skill
• Beginners

Short answer: a Copilot agent skill is a folder with a required SKILL.md file (plus optional scripts and resources). Copilot loads that folder when the task matches the skill's description. For one repo, put skills under .github/skills/, .claude/skills/ or .agents/skills/. For every project on your machine, use ~/.copilot/skills/ or ~/.agents/skills/. The file needs a YAML header with name and description. You can also discover and install skills with gh skill in GitHub CLI (public preview, CLI 2.90.0+). Skills are for a specific kind of task; custom instructions are for rules that should apply almost every time; a custom agent is a reusable specialist with its own toolset.

What a Copilot skill is

GitHub's docs call them agent skills: folders of instructions, scripts and resources that Copilot can load when they are relevant. The format follows the open Agent Skills specification, the same idea Claude Code, Cursor, Codex and Antigravity use (see our SKILL.md examples page).

• Loaded when needed: Copilot reads the skill's name and description, then injects the full SKILL.md into context only when the prompt matches.
• Can include helpers: scripts, templates and other files in the skill folder are discovered with the skill.
• Where it works: Copilot app, Copilot CLI, Copilot cloud agent, Copilot code review, and agent mode in Visual Studio Code, Visual Studio and JetBrains IDEs (IDE support depends on your version; see GitHub's feature matrix).

Where the skills folder goes

# One project only (pick one of these three)
mkdir -p .github/skills/write-pr-summary
# or: mkdir -p .agents/skills/write-pr-summary
# or: mkdir -p .claude/skills/write-pr-summary
# -> write .../write-pr-summary/SKILL.md

# Every project on this computer (pick one)
mkdir -p ~/.copilot/skills/write-pr-summary
# or: mkdir -p ~/.agents/skills/write-pr-summary

Each skill gets its own subdirectory. Names should be lowercase with hyphens (for example webapp-testing). The required file inside must be named exactly SKILL.md.

.github/skills/write-pr-summary/
├── SKILL.md              # Required: YAML header + steps
└── (optional) scripts/   # Scripts or other files the skill can use

Supported locations can differ by surface. For personal skills in cloud sandbox sessions, GitHub says to include them in .copilot/skills in your dotfiles repository (that does not apply to GitHub Actions-based sessions). Use the setup guide for the surface you are on rather than assuming a personal skill is available in the cloud.

The SKILL.md format

SKILL.md is Markdown with YAML frontmatter between two --- lines, then your steps.

Write the description like a job ad: what it does and the words people would type. Weak: "Helps with PRs." Better: "Drafts a short pull request summary from the current branch changes. Use when asked to write a PR description."

Skills vs agents vs instructions

This is the comparison people search for. GitHub's own customization comparison puts it this way:

• Instructions, not skills: "Use TypeScript, prefer small PRs, never commit secrets." That belongs in copilot-instructions.md / path instructions / AGENTS.md.
• Skills, not instructions: a multi-step release-notes workflow or a CI debugging checklist that would bloat every chat if it were always loaded.
• Custom agent, not skill: you need a different toolset or a named specialist you select for a session (or delegate to as a subagent). A skill alone is enough when instructions and resources are all you need.

Skills can also describe how to use MCP tools. For access to an outside system, add an MCP server; the skill can then say how to use those tools.

Install skills with gh skill (public preview)

gh skill is a GitHub CLI command to search, preview, install, update and publish agent skills from GitHub repositories. GitHub's docs and changelog mark it as public preview and subject to change. You need GitHub CLI 2.90.0 or later.

Safety: skills are not verified by GitHub. They may contain prompt injections, hidden instructions or malicious scripts. Always inspect with gh skill preview before you install.

# Needs GitHub CLI 2.90.0 or later. gh skill is public preview.
gh skill search TOPIC
gh skill preview OWNER/REPOSITORY SKILL
gh skill install OWNER/REPOSITORY SKILL
# Example from GitHub's docs:
gh skill install github/awesome-copilot documentation-writer
# Pin a version (or use @TAG / @SHA):
gh skill install github/awesome-copilot documentation-writer --pin v1.2.0
# Other agent / user scope:
gh skill install github/awesome-copilot documentation-writer --agent claude-code --scope user
gh skill update --all
gh skill publish --dry-run

By default, installs target Copilot at project scope. Use --agent and --scope (project or user) for another host or personal install. At project scope, several agents (including Copilot, Cursor, Codex, Gemini CLI and Antigravity) share .agents/skills, so one install can cover more than one tool.

GitHub's docs also point at community collections such as github/awesome-copilot and show installing from it. You can still download a skill folder by hand and move it into one of the paths in the table above (GitHub links awesome-copilot.github.com/skills/ for that).

How Copilot uses a skill

• Automatic: Copilot decides from your prompt and each skill's description. When it picks one, it injects that SKILL.md into the agent's context.
• By name in Copilot CLI: include the skill with a slash, for example Use the /frontend-design skill to create a responsive navigation bar in React.
• Code review: for Copilot code review on GitHub, a review-focused directory name like code-review helps. Skills already in .github/skills can also be used when they are relevant.

# Inside an interactive Copilot CLI session
/skills list
/skills info write-pr-summary
/skills reload
# Ask Copilot to use a skill by name:
Use the /write-pr-summary skill on this branch.
# From your shell (before a session):
copilot skill list

Examples you can copy

The first example matches the shape of GitHub's own sample (name + description + steps). The next three are examples we wrote for this page, using only fields GitHub documents (name, description). Change the steps to fit your project. Save each as SKILL.md inside a folder with the same name.

1. Write a pull request summary (our example)

---
name: write-pr-summary
description: Drafts a short pull request summary from the current branch changes. Use when asked to write a PR description, PR summary, or pull request body.
---

# Write a pull request summary

1. Look at the changed files on this branch (git status and the diff).
2. Write a short summary: what changed, why, and how to test it.
3. Use plain English. Keep it under 10 lines.
4. Do not invent features that are not in the diff.

2. Debug failing CI (our example)

---
name: debug-failing-ci
description: Helps debug a failing GitHub Actions workflow or CI check. Use when a pull request check is red, a workflow failed, or the user asks why CI broke.
---

# Debug a failing CI check

1. Find the failed workflow or check name from the pull request.
2. Read the failure message. Quote the first real error line (not just "Process completed with exit code 1").
3. Say whether the problem looks like a test failure, a build error, a missing secret, or a flaky step.
4. Suggest the smallest fix. Do not rewrite unrelated files.
5. If you cannot see the logs, tell me exactly which log file or job to open.

GitHub's own longer sample for Actions debugging (with MCP tool names like list_workflow_runs) is on the Adding agent skills page if you use the GitHub MCP Server.

3. Add an environment variable safely (our example)

---
name: add-env-safely
description: Adds a new environment variable or API key without leaking secrets. Use when the user adds a key, token, secret, or .env setting.
---

# Add an environment variable safely

1. Add the variable name to .env.example with an empty value. Never put a real secret there.
2. Ask me to paste the real value into .env myself. Do not print the value back.
3. Check that .env is listed in .gitignore. If it is missing, add it and tell me.
4. Read the variable in one place in the code, with a clear error if it is missing.
5. Tell me where to set it on the host (for example GitHub Actions secrets or the hosting dashboard).

4. Code review notes (our example)

---
name: code-review
description: Reviews a pull request or diff for bugs, missing tests, and unclear naming. Use when asked to review a PR, review a diff, or leave review comments.
---

# Code review notes

1. Summarize what the change is trying to do, in two sentences.
2. List concrete issues: bugs, missing tests, secrets, and naming that will confuse the next person.
3. For each issue, give the file and a short suggested fix.
4. End with a one-line "ship / needs changes / needs tests" call.
5. Stay polite and specific. No filler.

The directory name code-review matches GitHub's tip for Copilot code review. More cross-tool SKILL.md samples: SKILL.md examples. Claude-only extras: Claude Code skills examples.

Same idea in Claude Code, Cursor and Antigravity

The SKILL.md format is shared. The folder path is what changes:

• Claude Code: .claude/skills/ (project) and ~/.claude/skills/ (personal)
• Cursor: .agents/skills/ or .cursor/skills/
• Antigravity: .agents/skills/ and ~/.gemini/config/skills/

.agents/skills/ is a good shared project folder for Copilot, Cursor, Codex and Antigravity. Claude Code wants .claude/skills/ (which Copilot also reads). Details and a symlink tip: SKILL.md examples for every tool.

Skill not showing up?

• Wrong file name or depth: it must be <skills-dir>/<name>/SKILL.md, not a lone file in the skills root.
• Name mismatch: name should be lowercase with hyphens and typically match the folder.
• Broken YAML: first line must be ---, close it with another ---, and avoid unquoted colons that break the description. See the errors section on SKILL.md examples.
• CLI session started before you added it: run /skills reload, then /skills info <name>.
• Never gets picked: put the trigger words in the description ("failing CI", "PR summary"). Or call it with /name in Copilot CLI.
• Installed a third-party skill: preview it first. If something feels off, remove it (/skills remove in Copilot CLI, or delete the folder / use gh skill update/remove flows for CLI-managed installs).

Related

• SKILL.md examples for every tool (format, frontmatter, where the folder goes)
• copilot-instructions.md examples (7 copy-paste instruction files)
• Claude Code skills examples (7 copy-paste SKILL.md files)
• Google Antigravity skills (skills folder, SKILL.md, workflows vs skills)
• Cursor rules vs skills
• GitHub Copilot vs Cursor vs Claude Code (prices side by side)
• GitHub Copilot AI credits explained (what they cost and how to save)
• Free rules file generator

Sources

• GitHub Docs: About agent skills
• GitHub Docs: Adding agent skills for GitHub Copilot
• GitHub Docs: Adding agent skills for GitHub Copilot CLI
• GitHub Docs: Comparing Copilot customization features
• GitHub CLI manual: gh skill
• GitHub CLI manual: gh skill install
• GitHub Changelog: Manage agent skills with GitHub CLI (Apr 16, 2026)
• Agent Skills specification

Every folder, field and command here was checked Nov 7, 2026 on GitHub's own Copilot docs and the GitHub CLI manual. Agent skills and gh skill are still changing (gh skill is public preview). If something here no longer matches, tell us at [email protected].