Skills: Knowledge Your Agent Can Load

A skill is a folder of instructions your agent loads automatically when it fits the task.

What is a skill?

A skill is a folder that contains a file called SKILL.md. That file holds instructions. When a task matches the skill, Claude loads the instructions on its own. You can also call a skill directly, with /skill-name.

The structure of SKILL.md

Every SKILL.md starts with a YAML header between two --- lines. That header holds fields like name and description. After the header comes the actual text: the instructions Claude receives. A skill can include other files in the same folder, for example a reference.md file or a script. Claude only loads those extra files when it actually needs them.

Skill or slash command?

Slash commands first existed only as plain markdown files in .claude/commands/. Those files still work today. But custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create the same /deploy command. A skill can additionally bring a whole folder of files along. And Claude can load it automatically, as soon as it fits the task.

When is a skill worth writing?

Do you keep typing the same instructions into chat, over and over? Has a section of your CLAUDE.md grown into a whole procedure? That's a good moment to turn it into a skill. A skill only loads its text when it's actually needed. That saves context, compared to a long CLAUDE.md, which always loads in full.

Where skills live

Personal: ~/.claude/skills/<name>/SKILL.md - available in all your projects
Project: .claude/skills/<name>/SKILL.md - this project only
Plugin: <plugin>/skills/<name>/SKILL.md - wherever the plugin is enabled