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

ScopeFolders 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:

RuleAgent Skills specVS Code & Copilot
One SKILL.md per skillWarnsNotes it
Frontmatter starts on line 1 and is closedFailsWarns
Frontmatter is valid YAML and reads as writtenFailsWarns
No symbolic links in the skillWarnsNotes it
Has a nameFailsWarns
The name is at most 64 charactersFailsWarns
The name matches its folderFailsWarns
The name avoids the reserved words anthropic and claudeWarnsNot checked
The name has no angle bracketsFailsWarns
The name has no namespace prefixFailsWarns
The name has no hidden characters or odd spacingFailsWarns
The name says what the skill doesNotes itNot checked
Has a descriptionFailsWarns
The description is at most 1,024 charactersFailsWarns
The description says when to use the skillNotes itNot checked
The description leads with the main jobNotes itNot checked
Only the six spec fieldsWarnsNotes it
Has a license fieldNotes itNot checked
compatibility is text of 1 to 500 charactersFailsNotes it
metadata maps text keys to text valuesFailsNotes it
allowed-tools is one space-separated stringWarnsNotes it
No install records in metadataWarnsNot checked
The body is at most 500 linesWarnsNot checked
The body is under about 5,000 tokensWarnsNot checked
Reference files are linked from SKILL.mdNotes itNot checked
Long reference files start with contentsNotes itNot checked
No dated instructionsNotes itNot 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.