How to Create Your Own Claude Code Skill (SKILL.md, Step by Step)

A Claude Code skill is not a plugin, a package, or a build step. It is one markdown file — SKILL.md — sitting in its own folder, written in plain language an AI can follow. Which raises the obvious question: if it's just a file, why would anyone pay for one?

Fair question, and this post answers it honestly by showing you the whole DIY process first. Building a skill is genuinely doable. What it costs is time — specifically, the distillation work of turning a framework you know into instructions an agent follows reliably. Here is how to do it well, and how to decide whether to.

If you need the background first, start with what Claude Code skills are. If you already have a skill file and just need it running, use the install guide instead.

Step 1: Pick one job, not one topic

The skills that get used are hired for a job: "score my habits before I try to change them," "audit where my attention went last week." The skills that rot are topic dumps — everything someone knows about productivity in one file.

So start from a single recurring job and the framework that does it best. One book usually maps to one skill: Atomic Habits is a habits skill because the job is habit design, and its commands — /habit-scorecard, /habit-audit, /habit-stack, /habit-tracker — are each one step of that job.

Write the job in one sentence before you write anything else. If you can't, the skill isn't scoped yet.

Step 2: Distill the framework into commands

This is the real work. Read (or re-read) your source with a highlighter and extract the procedures, not the summaries. A chapter that explains a concept becomes useful only when you can rewrite it as: ask these questions, in this order, then produce this output.

Each procedure becomes a named command. A good command has three parts:

• Trigger and inputs: what the user types, and what the skill should ask for if they didn't provide it.
• Steps: the numbered process, in the order the framework prescribes — not the order that feels natural to you.
• Output format: what the user gets back. A table, a scored list, a plan. Vague output instructions produce vague output.

Expect this step to take the longest by far. Distilling one book into four to six tight commands is an afternoon of careful work if you know the material cold, and longer if you don't — and the first version will still need testing, because instructions that read clearly to you will ambush the model in places you didn't expect.

Step 3: Write the SKILL.md file

Create the folder and file (the install mechanics are covered in full in the install guide):

mkdir -p ~/.claude/skills/my-skill

Inside it, SKILL.md follows a simple anatomy:

# My Skill

What this skill does, and when to use it — two or three sentences
Claude Code can match against what the user is asking for.

## /my-command

Purpose: one line.
Ask for: the inputs, if the user didn't give them.
Steps:
1. ...
2. ...
Output: exactly what to return, and in what shape.

Repeat the command block for each command from Step 2. Keep the whole file focused: every line should either tell the agent when the skill applies or how to do the work. Background essays about the framework belong in your notes, not in the file the agent loads.

Step 4: Install, restart, and test like a skeptic

Restart Claude Code so it discovers the new folder, then run each command on a real case — not a toy example. Test the edges on purpose: give a command half its inputs, give it a case the framework handles badly, and watch whether the steps hold or the model improvises. Where it improvises, your instructions have a gap. Tighten them and retest.

Budget a few rounds of this. The difference between a skill that demos well and one you reach for weekly is almost entirely this loop.

The honest math: build vs. buy

Nothing above requires permission or money, which is exactly why we publish it. The trade is time:

• Build when the framework is yours — your team's process, your niche expertise, something no catalog sells. One skill, one afternoon plus testing, and it's tailored to exactly how you work.
• Buy when the framework is a book someone else already distilled. Each BookSkills skill is $7 one-time — against an afternoon of distillation and testing per book, most people are buying back their afternoon, not the file.

Scale changes the answer again. Annual Access unlocks all 43 catalog skills for $79.99/year, and the arithmetic stays honest: at $7 a single, Annual only pays off once you'd otherwise buy twelve or more titles (eleven singles cost $77; twelve cost $84). Building twelve book skills yourself is twelve afternoons. One job to solve? Build it or buy the single. A shelf of frameworks you keep reaching for? That's the case Annual exists for.

Our ranked list of the best Claude Code skills shows what the finished versions look like across ten jobs, if you want a quality bar to build against.

Try the pattern on the free one first

The fastest way to learn what a good SKILL.md looks like from the inside is to install one and read it. The Atomic Habits skill is free: download it, open the file before you install it, and look at how the four Laws of Behavior Change became /habit-scorecard, /habit-stack, and the rest. Then decide, with the template above and the time math in front of you, which of your frameworks you'll build — and which you'd rather just have.