Claude Code skills: what they are and how to write your first one

Most people use Claude Code by explaining the same jobs over and over: how to write a changelog, how to review a pull request, how to deploy. A skill is how you explain it once.

#What a skill is

A skill is a folder with one required file, SKILL.md. The file starts with a short frontmatter block that says what the skill is for, followed by the instructions Claude should follow when it uses it.

What makes skills efficient is how they load. On every turn Claude only sees each skill's description. The full body of SKILL.md is loaded when the skill is actually used, and from then on it stays in the conversation. So you can have hundreds of skills installed and only pay for the few you use.

#Where skills live

Project skills are the ones to commit to git: the whole team gets the same procedures.

#Write your first skill

Here is a complete skill that writes a changelog entry. Create ~/.claude/skills/changelog/SKILL.md:

---
name: changelog
description: Write a changelog entry from the commits since the last git tag. Use when the user asks for release notes, a changelog, or what changed since the last release.
---

# Changelog entry

1. Find the latest tag with `git describe --tags --abbrev=0`.
2. List the commits since it with `git log <tag>..HEAD --oneline`.
3. Group them under Added, Changed and Fixed. Skip merge commits and chores.
4. Write each line from the user's point of view, not the code's.
5. Keep it under ten lines. Show it to the user before writing it to CHANGELOG.md.

That's the whole thing. The file must start with --- on its very first line, or the frontmatter isn't recognised.

#The description does the work

Claude decides whether to use a skill by matching your request against its description. A vague description means the skill never fires; a precise one means it fires at the right moment.

A good description says two things:

• What the skill does, in plain words.
• When to use it, including the phrases people actually say ("release notes", "what changed").

The name field is optional and defaults to the folder name. The description and the optional when_to_use field together are limited to 1,536 characters, which is plenty.

#Run it yourself

You don't have to wait for Claude to pick a skill. Type its name as a command:

/changelog

Anything after the name is passed in as arguments, available inside the skill as $ARGUMENTS. For a skill you only ever want to run by hand, such as a deploy, add disable-model-invocation: true to the frontmatter so Claude never starts it on its own.

#Useful optional fields

#Keep skills small

The pattern that works best is one job per skill, with a short SKILL.md. If a skill needs a long reference, such as an API spec or a style guide, put it in a separate file in the same folder and tell Claude when to read it. It's only read when needed, which keeps every session lighter.

Skills can also run shell commands before the instructions reach Claude, with an inline !`command` block, so the skill starts with fresh data such as the current git status.

#Questions

#Do skills use up my context window?

Only a little until they're used. Every skill's description is included on each turn; the full instructions load only when the skill runs. That's why descriptions should be precise rather than long.

#What's the difference between a skill and CLAUDE.md?

CLAUDE.md holds facts Claude should always know about a project, and it's loaded every session. A skill holds a procedure Claude follows only when a task calls for it.

#Can I share skills with my team?

Yes. Put them in the repository's .claude/skills/ folder and commit it. Everyone who works in the repository gets them.

#Sources

• Claude Code docs: Skills