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
| Scope | Folders 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:
| Rule | Agent Skills spec | Claude Code |
|---|---|---|
| The file is named SKILL.md | Fails | Warns |
| 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 |
| The skill sits one folder below its skills folder | Warns | Not checked |
| No symbolic links in the skill | Warns | Notes it |
| Has a name | Fails | Notes it |
| The name is at most 64 characters | Fails | Not checked |
| The name uses lowercase letters, digits and single hyphens | Fails | Warns |
| The name matches its folder | Fails | Notes it |
| The name avoids the reserved words anthropic and claude | Warns | Notes it |
| The name has no namespace prefix | Fails | Not checked |
| The name is not one Claude Code reserves | Not checked | Fails |
| Has a description | Fails | Warns |
| The description is at most 1,024 characters | Fails | Not checked |
| The description has no angle brackets | Warns | Not checked |
| Description and when_to_use fit in 1,536 characters | Not checked | Warns |
| The description says when to use the skill | Notes it | Not checked |
| The description is in the third person | Not checked | Notes it |
| 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 | Warns |
| allowed-tools is one space-separated string | Warns | Not checked |
| No install records in metadata | Warns | Not checked |
| The body is at most 500 lines | Warns | Notes it |
| The body is under about 5,000 tokens | Warns | Notes 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.