How to Write Claude Code Skills: Complete Tutorial

I run seventeen claude code skills in production, and the ones that matter were not the ones I planned — they were the workflows I caught myself re-typing, which is exactly what claude code skills are built to kill. A skill is a folder with a markdown file in it. That is the whole format. Most people never write one because the documentation makes it sound like infrastructure when it is closer to writing a good note to yourself, except the note runs.

This is the tutorial I wish I had: what a skill actually is, the one field that decides whether it ever runs, and how to ship your first one tonight.

What are Claude Code skills?

A skill is a directory containing a SKILL.md file. That file has YAML frontmatter with two required keys — name and description — and a markdown body with instructions. That is the entire contract. Everything else is optional: helper scripts, reference docs, examples in subfolders.

The mechanism is what makes claude code skills useful rather than templated prompts. At session start, Claude reads only the frontmatter of every installed skill — the name and the description, a few dozen tokens each. The full body stays on disk. When a task comes in that matches a skill’s description, Claude loads that body into context and follows it. This is progressive disclosure: you can have fifty skills installed and pay the context cost of only the one you actually use.

That single design choice is why a skill beats a 5,000-token system prompt that tries to do everything. I wrote about that monolith problem in how to build AI agent skills — the same modular logic applies here, just packaged in Claude Code’s specific folder format. If you are still setting up the CLI itself, start with the Claude Code setup guide first; this tutorial assumes a working install.

Where skills live and how Claude finds them

Two locations, and the distinction matters:

1. Personal skills — ~/.claude/skills/. These follow you across every project. Good for your own habits: a commit-message style, a research routine, a writing voice.
2. Project skills — .claude/skills/ inside a repo. These get committed to git. Every teammate and every cron job that checks out the repo inherits them automatically.

Each skill is its own subfolder. The folder name becomes the skill’s invocable name. So ~/.claude/skills/changelog/SKILL.md gives you a skill Claude can call as changelog.

Almost all of mine live as project skills. When a scheduled job fires at 3am with no human in the loop, it boots from the repo and the skills are just there — same as the rest of the codebase. That is the part the launch posts undersell: skills are not a personal-productivity feature, they are how you give an autonomous agent a stable, versioned set of procedures.

Writing your first SKILL.md

Here is a complete, runnable skill. It packages a release-notes workflow:

---
name: release-notes
description: Use when cutting a release or when the user asks for
  a changelog, release notes, or "what changed since last tag."
  Generates grouped, human-readable notes from git history.
---

# Release Notes

When invoked:

1. Run `git describe --tags --abbrev=0` to find the last tag.
2. Run `git log <last-tag>..HEAD --oneline` for the commit range.
3. Group commits into: Features, Fixes, Internal. Drop merge
   commits and anything tagged `chore:`.
4. Write 1-2 sentences per user-facing change in plain language.
   No commit hashes in the output. No "various improvements."
5. Output as markdown under an `## <version>` heading.

Never invent a change that is not in the log. If the range is
empty, say so and stop.

Save that to .claude/skills/release-notes/SKILL.md, and Claude can invoke it the moment you say “cut release notes.” No restart, no registration step — the folder is the registration.

Notice what the body does. It gives numbered, deterministic steps, states the bash commands by name, and ends with a hard constraint (“never invent a change”). That last line is doing real work: skills are instructions, so the failure modes of a bad instruction — vagueness, hallucinated output, scope creep — are your failure modes too. Treat the body like a system prompt for a narrow task, because that is functionally what it is.

The description field decides everything

The description is the only part of your skill Claude reads before deciding whether to use it. Get it wrong and the skill sits on disk, perfectly written, never invoked.

The mistake everyone makes is writing a description that says what the skill is instead of when to use it:

# Weak — describes the noun
description: 'A skill for release notes.'

# Strong — describes the trigger
description: 'Use when cutting a release or when the user asks for
  a changelog, release notes, or "what changed since last tag."'

The strong version embeds the phrases a real request would contain. Claude is matching the incoming task against your description, so the description should read like a list of situations that should fire it. Include the literal phrases users type — “what changed,” “changelog” — because that is what the match lands on.

When a skill does not run, the description is the first suspect, not the body. More silent skill failures get fixed by rewriting one sentence of frontmatter than by touching a single line of instructions. The pipeline does not error, it just quietly does nothing — the same expensive failure mode that shows up in every AI agent skill build where a wrong trigger causes a silent non-run.

Adding scripts, references, and structure

A skill is not limited to prose. The folder can hold anything, and the body references files by relative path:

.claude/skills/release-notes/
  SKILL.md
  scripts/
    group_commits.py
  reference/
    voice-guide.md

In the body you write “run scripts/group_commits.py to bucket the commits” or “match the tone in reference/voice-guide.md.” Claude reads those files only when the step calls for them — progressive disclosure again, one level deeper. This keeps the main SKILL.md short. If the body crosses a few hundred lines, push the detail into reference files and link them, so the always-loaded part stays cheap.

Scripts are how you make a step deterministic instead of asking the model to do arithmetic it will sometimes get wrong. Anything mechanical — parsing, counting, formatting, calling an API with a fixed shape — belongs in a script the skill invokes, not in the model’s head. If your skill needs to reach external tools, that is the boundary where MCP servers come in; a skill can instruct Claude to call an MCP tool the same way it calls a local script.

For genuinely heavy work, a skill can dispatch a subagent — a separate Claude instance that does isolated work and reports back. That pattern is worth using when a step needs its own large context budget; the mechanics are in how to build a subagent in Claude Code.

Testing and shipping the skill

Skills are live the instant the file exists, which cuts both ways — a broken skill is also live instantly. The loop:

1. Write the SKILL.md.
2. Start a fresh session and give it a task that should trigger the skill. Confirm Claude loads it. If it does not, the description is too vague — rewrite it and retry.
3. Give it an adjacent task that should not trigger it. Confirm it stays dormant. Over-eager skills are as bad as silent ones.
4. Run the happy path end to end and read the output against the constraints you wrote.
5. Commit. For project skills, that is the deploy.

The fresh-session step is non-negotiable. The skill’s whole value is that Claude decides to use it on its own; testing it by manually forcing it tells you nothing about whether the description works. If you are driving all this from the terminal, the Claude Code CLI guide covers the session and invocation commands this loop depends on.

Once you have a few skills, you have built a small agent: a set of procedures Claude composes on demand. That is the same architecture behind everything I run, and if you want the full picture of wiring skills, subagents, and tools into one system, building Claude Code subagents is the next step up from here.

Want the skill built for you

Writing one good skill takes an afternoon. Writing fifteen that compose cleanly — with tuned descriptions that fire at exactly the right moment and helper scripts that never drift — takes a different kind of attention. Most of it spent on the boring parts: the description phrasing, the constraint lines, the script boundaries.

That is what Skill Creator does. You describe the workflow you keep repeating; it ships a production-structured skill — frontmatter tuned for reliable triggering, body kept lean, scripts factored out, the whole folder ready to commit. If you would rather hand off the structure work and keep the workflow, that is the done-for-you path. And if your need is a full custom agent rather than a single skill, the intake for a build starts there.

Either way, the on-ramp is the same: find the one thing you typed twice this week, and turn it into a folder.