What Claude Code skills are and how to write one

A Claude Code skill is a folder with a SKILL.md file. Learn where skills live, which frontmatter fields matter and how to write and test your first one.

10 October 2026

Claude Code skills package instructions, reference material and scripts so Claude can use them when a task calls for them. This guide covers what a skill is, where it lives, and how to write and test one, based on the Claude Code skills documentation and Anthropic’s engineering post Equipping agents for the real world with Agent Skills.

What a skill is

The documentation puts it simply: “Create a SKILL.md file with instructions, and Claude adds it to its toolkit.” Claude uses a skill when it is relevant, and you can also run one directly by typing /skill-name.

Skills follow the Agent Skills open standard. Claude Code adds its own extensions on top, such as invocation control, running a skill in a subagent, and injecting the output of a shell command into the skill before Claude reads it.

Custom slash commands have been merged into skills: according to the docs, .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy.

Why skills save context

Anthropic describes skills as built on progressive disclosure, in three levels:

1. Metadata. The name and description give Claude “just enough information” to know when each skill should be used.
2. The SKILL.md body. Claude reads it in full only when the skill looks relevant.
3. Linked files. Extra files in the skill folder are opened only when they are needed.

The Claude Code docs draw the practical consequence: unlike CLAUDE.md content, a skill’s body loads only when it is used, so long reference material costs almost nothing until you need it.

Where skills live

The location decides who gets the skill. From the documentation:

Organizations can also deploy skills through managed settings, and nested .claude/skills/ folders inside a subdirectory apply to sessions started in or below it.

Anatomy of SKILL.md

A SKILL.md file has two parts: YAML frontmatter between --- markers, which tells Claude when to use the skill, and Markdown instructions that Claude follows when the skill runs. The frontmatter is only read when the opening --- is the first line of the file.

In Claude Code every frontmatter field is optional, and description is the one Anthropic recommends. The fields you will reach for first:

One portability note from the docs: outside Claude Code (claude.ai uploads, the Skills API), only name, description, license, compatibility, metadata and allowed-tools are accepted, and other keys cause an error. If you plan to reuse a skill there, stick to those fields.

Write your first skill

Here is a small personal skill that drafts release notes from recent commits. Create the folder and file:

~/.claude/skills/release-notes/
└── SKILL.md

Then write SKILL.md:

---
description: Drafts release notes from recent git commits. Use when the user asks for release notes, a changelog entry or a summary of what shipped.
---

## Instructions

1. Run `git log --oneline` for the range the user gives, or since the latest tag if none is given.
2. Group the commits into Added, Changed and Fixed.
3. Write one plain-English line per change. Skip merge commits and formatting-only changes.
4. If the range has no commits, say so instead of inventing entries.

Two things carry most of the weight. The description names both what the skill does and the situations that should trigger it, because that text is what Claude sees before deciding to load the skill. The instructions are concrete steps, including what to do when there is nothing to report.

Add supporting files

The docs recommend keeping SKILL.md under 500 lines and moving detailed material into separate files that the skill references:

my-skill/
├── SKILL.md        (overview and navigation)
├── reference.md    (loaded when needed)
├── examples.md     (loaded when needed)
└── scripts/
    └── helper.py   (executed, not loaded)

Mention each file from SKILL.md so Claude knows when to open it. Anthropic’s post notes that skills can also bundle code “for Claude to execute as tools at its discretion”, which suits steps that must be deterministic.

Test it

• Automatic use: ask something that matches the description, for example “Write release notes since the last tag.”
• Direct use: type /release-notes.
• Check it loaded: run /skills to list the skills Claude Code has found.
• Edit live: Claude Code watches skill directories, so changes to an existing skill take effect without a restart.

If Claude never picks the skill up on its own, the description is usually the problem: make it say plainly when the skill applies.

Share it

Commit .claude/skills/ to share project skills with your team, or put the skill in a plugin’s skills/ directory to distribute it more widely. Anthropic’s advice on the other side of sharing: install skills only from trusted sources, and audit the bundled files, dependencies and any instructions that reach out to external networks before you use a skill you did not write.