How to write a Claude Code skill that actually works

The first time I ran the same prompt twice, once with a skill and once without, the difference was bigger than I expected. I'd asked Claude to write a LinkedIn post about a soundboard I built for hockey games. Without the skill I got the post you've seen a thousand times, with the bullet points, the little life lesson at the end and the invitation to send me a message. With the skill turned on, it wrote about the rink Wi-Fi cutting out in the second period and the horns still going off anyway, because the sound files were already sitting on the tablet. That one sounded like somebody who has actually stood in a cold rink. I ran both through a small script that counts the habits my skill tells Claude to avoid, and the plain version had eleven of them. The other had none.

That skill is just a text file, and every rule in it is something I got tired of correcting by hand. Once you see how little there is to one, it's hard not to start writing your own, so here's how they work and how I went from a first draft that did nothing to one that changed how my commits look.

What a skill actually is

A skill is a folder with a single file in it. In your home folder there's a .claude folder, inside that is skills, and inside that you make a folder named after the skill with one file called SKILL.md (capitals on SKILL). If it only matters for one project, the same structure goes in that project's .claude folder instead, and you can commit it so everyone on the team picks it up. The file opens with a short header between two lines of three dashes, holding a name and a description, and everything under that is plain English.

The part that trips most people up is how Claude decides to use it. It doesn't read every skill all the time. What it reads in every session is the descriptions, and when something you ask lines up with one of them, that's when it opens the whole file. It's a judgment call rather than a keyword match, which means the description isn't really a label for you. It's the trigger. If you ever want to skip the guessing, you can type a slash and the skill's name and it runs right away.

A first draft that did nothing

I built mine for commit messages, since every developer writes them and most of them say "fixed stuff." My first draft was about as thin as a skill can get:

---
name: commit-message
description: Helps with git.
---

Write good commit messages.

I staged a change on a ticket branch and asked Claude to commit it. It loaded the skill and wrote "Skip blank rows and trim whitespace in roster import," which is a perfectly good commit message. It's also exactly what Claude writes with no skill at all. It didn't run the tests and it didn't add the ticket number, so the skill hadn't changed a thing.

There were two problems with it. "Helps with git" never says when the skill should be used, and the only reason it fired was that it happened to be called commit-message and I happened to say commit. Add a few more skills and that kind of luck runs out. The bigger problem was the body. Telling Claude to write good commit messages is asking for something it already does, and a skill that only asks for what Claude would do anyway can't change anything.

The version that works

---
name: commit-message
description: Commit my changes the way I do it. Use whenever I ask to commit, write a commit message, or summarize my changes.
---

# How I commit

1. Run `npm test` first. If anything fails, don't commit. Tell me what broke.
2. Pull the ticket number from the branch name (like RST-42) and end the message with "Refs RST-42".
3. Start with a verb, first line under 60 characters, then 1-3 lines on WHY.
4. Never write "misc fixes", "updated files", or "WIP".

The description now says what the skill does and when to use it, in the words I'd actually type. The body stopped being style advice and became my process, the things a new hire would get wrong on their first day.

I opened a fresh session, staged the same change and asked the same way. This time it ran the tests first and only committed once they passed. The first line was the same, but there was a short reason underneath it and "Refs RST-42" at the bottom, pulled straight from the branch name. Then it told me something I hadn't asked about, which was that my one test doesn't cover blank rows, so the change it had just committed wasn't really tested yet. All of that came from about two minutes of editing.

Making sure it fired

The easiest check is to watch for Claude loading the skill by name. If it doesn't, run /skills and see whether it's listed. When it's listed but not firing, the description needs the words you actually used when you asked. When it isn't listed at all, the problem is usually the folder name or the dashes at the top of the file. For anything that takes an action, like committing or deploying, there's also a setting you can add to the header so it only runs when you call it with the slash command.

Building a handful of these taught me a couple of things. The good rules come from real corrections. I never sat down to write a style guide, I just noticed when I was deleting the same phrase out of a draft for the third time and wrote it down once. Small also beats clever. I run my side company without a finance person or a marketing person, so I wrote a skill for each of those roles, but only after trying one giant set of instructions that turned to mush.

I'd also skip installing fifty skills because someone online said to. Every description sits in Claude's context at the same time, and they start competing with each other. If yours runs to pages, it's probably three skills pretending to be one, and any long reference material can live in a separate file in the same folder as long as the skill links to it.

The finished skill, a starter template and a one-page checklist are on the Ep 01 page, and the video shows all of it running.