Agent Skills

Claude Code

How Claude Code finds, installs and reads a skill, from its own docs, checked 26 Oct 2026.


Where it looks for skills

ScopeFolders it reads
This project.claude/skills/
All your projects~/.claude/skills/

From Claude Code’s own docs, checked 26 Oct 2026.


Install a skill

  • Copy the skill’s folder, with its SKILL.md at the top, into .claude/skills/ in your project, or into ~/.claude/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 Claude Code, starting from Install skills in Claude Code.

Fields it reads

Beyond the six fields every SKILL.md can hold, Claude Code reads when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, disallowed-tools, model, effort, context, agent, background, hooks, paths and shell.

SKILL.md sets out the six fields and their limits.


How the format check reads it

The format check on qai.io/skills has a row of its own for Claude Code: Claude Code reads its own extra fields, ignores unknown ones, and still loads a skill whose frontmatter is broken, without its fields.

Where that differs from the Agent Skills spec row, rule by rule:

RuleAgent Skills specClaude Code
The file is named SKILL.mdFailsWarns
One SKILL.md per skillWarnsNotes it
Frontmatter starts on line 1 and is closedFailsWarns
Frontmatter is valid YAML and reads as writtenFailsWarns
The skill sits one folder below its skills folderWarnsNot checked
No symbolic links in the skillWarnsNotes it
Has a nameFailsNotes it
The name is at most 64 charactersFailsNot checked
The name uses lowercase letters, digits and single hyphensFailsWarns
The name matches its folderFailsNotes it
The name avoids the reserved words anthropic and claudeWarnsNotes it
The name has no namespace prefixFailsNot checked
The name is not one Claude Code reservesNot checkedFails
Has a descriptionFailsWarns
The description is at most 1,024 charactersFailsNot checked
The description has no angle bracketsWarnsNot checked
Description and when_to_use fit in 1,536 charactersNot checkedWarns
The description says when to use the skillNotes itNot checked
The description is in the third personNot checkedNotes it
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 valuesFailsWarns
allowed-tools is one space-separated stringWarnsNot checked
No install records in metadataWarnsNot checked
The body is at most 500 linesWarnsNotes it
The body is under about 5,000 tokensWarnsNotes it

Validate a SKILL.md shows what Claude Code will reject in your file, with the fix.


Watch out for

  • A personal skill in ~/.claude/skills wins over a project skill with the same name.
  • New and edited skills load in the running session; if the skills folder did not exist when the session started, run /reload-skills.
  • Its docs list only .claude/skills folders, not the shared .agents/skills folder other agents read.
  • Cowork and cloud sessions do not read ~/.claude/skills; they load the skills enabled on your claude.ai account.