Guide · Skills

How to write Claude Code skills

Package a workflow as a skill: one folder with a SKILL.md. Claude loads it only when the task needs it, so it costs almost nothing the rest of the time.

Last updated 27 Oct 2026

Skill or CLAUDE.md?CLAUDE.md is loaded in full at the start of every session. A skill only puts its name and one-line description into the session. Claude reads the rest when a task matches. So rules you need every time go in CLAUDE.md, and a long "how to do X" goes in a skill.

1Make the folder

~/.claude/skills/
  arttie-reels/
    SKILL.md          <- required: frontmatter + instructions
    references/       <- optional: longer docs, loaded only when needed

~/.claude/skills/: your skills, in every project.
.claude/skills/ in a repo: project skills, shared through git.

The folder name is the skill name. You can also call it directly by typing / and its name.

2Write the frontmatter: this is the trigger

Here is a real one from the workspace where I draw Arttie. It makes short videos:

---
name: arttie-reels
description: Make an Instagram Reel (short 9:16 video) of Arttie with a hook, on-screen
  text, original background music and a Minion-style gibberish voice. Use when Arthur asks
  for a reel, a video, or an animated post for @arttie_0629.
---

The description is the only part Claude sees before deciding, so it must say what the skill does and when to use it. "Use when Arthur asks for a reel, a video, or an animated post" is what makes it load at the right time.

3Write the body as steps, not an essay

The body is read only after the skill triggers. Keep it to what Claude can't work out alone: the order of steps, the files to copy, the mistakes to avoid. The reels skill opens with its most important rule:

# Arttie reels

A reel is a folder reels/<title>/ with build.py (+ tts.ps1), reel.mp4, cover.png, caption.md.
The working reference is reels/it-worked-first-try/: copy its build.py and tts.ps1 into the
new folder and change only the story parts (scenes, overlays, timeline, phrases, music cues).
Don't rewrite the pipeline.

That one line heads off the most expensive mistake: Claude rebuilding a pipeline that already works.

4Move big reference material into extra files

If the body grows past a page or two, split the details into files next to SKILL.md and link them. Claude opens a reference file only when it needs that part. The graphify skill I use keeps its long docs in a references/ folder this way.

5Let Claude write the first draft

The best time to make a skill is right after you've done a task with Claude and it went well. While the session still remembers the steps, ask:

Turn what we just did into a skill in .claude/skills/<name>/SKILL.md. The description
must say what it does and when to use it. The body: the steps in order, the files to copy,
and the mistakes we hit. Leave out anything you'd know without it.

Then trim it. Drafts tend to explain things Claude already knows.

6Install skills other people wrote

Plugins can bring skills with them. I redesigned this site's home page with two installed design skills, frontend-design and ui-ux-pro-max. I asked Claude to review the home page with them, and it used their checklists to list what made the page look generic.

7Test the trigger

Start a new session and ask for the task in the words you'd normally use, without naming the skill. If it doesn't load, the description is too narrow. If it loads for unrelated tasks, it's too broad. Fix the description, not the body.

Every installed skill costs a little. Each skill's description sits in every session. A few dozen is fine; hundreds of vague ones add up and make Claude pick the wrong one. Delete skills you no longer use. More on this in how to save tokens in Claude Code.

Want something that runs every time, not only when Claude decides? That's a hook: Claude Code hooks, with examples.