An agent skill is a directory named after the skill containing SKILL.md: YAML frontmatter, then the instructions Claude follows once the skill is loaded.1
Fields
| Field | Required | Guidance |
|---|---|---|
name | Yes | Lowercase letters, numbers, hyphens; at most 64 characters; same as the directory name |
description | Yes | At most 1,024 characters; what the skill does and when to use it, in words users actually say |
allowed-tools | No | Restricts tools for read-only or sensitive workflows (see Least-privilege tool access) |
model | No | Selects a model for the skill |
1 name identifies the skill, description decides when it matches, and the body says what to do.1
Layout
my-skill/
├── SKILL.md
├── references/
├── scripts/
└── assets/Why the supporting folders exist is on Progressive disclosure.
Example
---
name: pr-description
description: Writes pull request descriptions. Use when creating or summarizing a pull request.
---
When writing a PR description:
1. Inspect the complete branch diff.
2. Explain what changed and why.
3. List the concrete changes and any renamed or deleted files.Related
- Subagent configuration file: the parallel format for subagents, which can list skills to preload.
- Source: Introduction to Claude Code Agent Skills