How to Build Your Own Claude Skill

Making your own Claude Skill is easier than most people expect. You are not writing a program. You are writing a note, and putting it where Claude will find it.

Here is one you can build right now.

Step one: make a folder

mkdir -p ~/.claude/skills/changelog

That line makes a folder. mkdir is short for “make directory”, and directory is just another word for folder. The ~ symbol means your home folder, wherever that lives on your computer.

You can also make the folder by clicking around normally. The command is just faster.

Step two: write the note

Inside that folder, make a file called SKILL.md and put this in it:

---
name: changelog
description: Write release notes in our style. Use this when
  someone asks for release notes, a changelog, or a summary
  of what changed.
---

# Release notes

Sort changes into Added, Changed, Fixed and Removed.
Leave out any group that is empty.

Write for someone who uses the product, not someone who
built it. "Search now handles apostrophes" is good.
"Fixed regex in tokeniser" is not.

One line per change.

Save it. That is a finished skill.

Step three: try it

Start a new chat with Claude and ask for release notes. It should find your skill on its own and follow your rules.

You can also run it directly by typing /changelog.

Two places a skill can live

~/.claude/skills/     just for you, works everywhere
.claude/skills/       inside one project, shared with your team

Use the first one for personal habits. Use the second for anything the whole team should follow.

The team option is genuinely useful. Rules written in a document somewhere get ignored. Rules that live inside the project get picked up automatically by everyone who works on it, including people who join later and were never told.

The one thing that decides whether it works

When Claude is deciding whether to use your skill, it does not read your instructions. It only reads the description.

Think of it like a label on a jar in a cupboard. You do not open every jar to see what is inside. You read the labels and open one.

So a badly labelled jar never gets opened, no matter how good the contents are.

Two rules for a good label:

• Say what it does and when to use it. Most people write the first half and forget the second. The second half is the part that does the matching.
• Use the words people actually say. If your team says “release notes” but your label says “changelog”, it will miss. Put both in.

When one file is not enough

my-skill/
├── SKILL.md
├── scripts/      small programs Claude can run
├── references/   longer notes, read only if needed
└── assets/       templates, logos, fonts

Keep SKILL.md short, and move long material into references/. Claude only opens those extra files when the job actually needs them, so a big pile of notes costs nothing while it sits unused.

Put anything with an exact right answer into scripts/. Checking a file, resizing images, adding up numbers — a small program does those perfectly every time, which beats asking a model to be careful.

Get Claude to write it for you

There is a skill whose whole job is building other skills. It is called skill-creator.

It sets up the folder, writes the label, and can test whether your description actually gets picked up. That last part is worth having, because a skill that quietly never fires is hard to spot on your own.

The full rules for the format are published at agentskills.io/specification, and there are nineteen finished examples to copy from at github.com/anthropics/skills.