Agent Skills
GitHub Copilot
How GitHub Copilot finds, installs and reads a skill, from its own docs, checked 26 Oct 2026.
Where it looks for skills
| Scope | Folders it reads |
|---|---|
| This project | .github/skills/, .claude/skills/ and .agents/skills/ |
| All your projects | ~/.copilot/skills/ and ~/.agents/skills/ |
From GitHub Copilot’s own docs, checked 26 Oct 2026.
Install a skill
- Copy the skill’s folder, with its SKILL.md at the top, into .github/skills/ in your project, or into ~/.copilot/skills/ for all your projects.
- Keep the folder named exactly as the name field in its SKILL.md, as The skill folder explains.
- On qai.io/skills, every skill’s page has the steps for GitHub Copilot, starting from Install skills in GitHub Copilot.
Fields it reads
Only the six fields every SKILL.md can hold; its docs name no fields of its own.
SKILL.md sets out the six fields and their limits.
How the format check reads it
The format check on qai.io/skills reads a skill for GitHub Copilot as VS Code & Copilot: VS Code reads skills one folder below .github/skills, .claude/skills or .agents/skills and falls back to the folder name when the name is missing or differs; GitHub's Copilot docs require the exact name SKILL.md.
Where that differs from the Agent Skills spec row, rule by rule:
| Rule | Agent Skills spec | VS Code & Copilot |
|---|---|---|
| One SKILL.md per skill | Warns | Notes it |
| Frontmatter starts on line 1 and is closed | Fails | Warns |
| Frontmatter is valid YAML and reads as written | Fails | Warns |
| No symbolic links in the skill | Warns | Notes it |
| Has a name | Fails | Warns |
| The name is at most 64 characters | Fails | Warns |
| The name matches its folder | Fails | Warns |
| The name avoids the reserved words anthropic and claude | Warns | Not checked |
| The name has no angle brackets | Fails | Warns |
| The name has no namespace prefix | Fails | Warns |
| The name has no hidden characters or odd spacing | Fails | Warns |
| The name says what the skill does | Notes it | Not checked |
| Has a description | Fails | Warns |
| The description is at most 1,024 characters | Fails | Warns |
| The description says when to use the skill | Notes it | Not checked |
| The description leads with the main job | Notes it | Not checked |
| Only the six spec fields | Warns | Notes it |
| Has a license field | Notes it | Not checked |
| compatibility is text of 1 to 500 characters | Fails | Notes it |
| metadata maps text keys to text values | Fails | Notes it |
| allowed-tools is one space-separated string | Warns | Notes it |
| No install records in metadata | Warns | Not checked |
| The body is at most 500 lines | Warns | Not checked |
| The body is under about 5,000 tokens | Warns | Not checked |
| Reference files are linked from SKILL.md | Notes it | Not checked |
| Long reference files start with contents | Notes it | Not checked |
| No dated instructions | Notes it | Not checked |
Validate a SKILL.md shows what GitHub Copilot will reject in your file, with the fix.
Watch out for
- gh skill install (GitHub CLI 2.90 or later, in preview) installs a given tag or commit with name@version, or with --pin, which also stops gh skill update from changing it.
- GitHub says the folders each surface reads differ, so do not assume a personal skill reaches Copilot cloud agent.
- In a running Copilot CLI session, run /skills reload after adding a skill.
- GitHub warns that pre-approving shell or bash in allowed-tools lets a skill run terminal commands without asking.