A Claude Code skill is a folder with one text file in it, and the file teaches Claude how to do one job the way you do it. You write it in plain sentences. You never write it again. The next time the job comes up, Claude opens the file, follows it, and does the job your way, including the parts you would otherwise forget to mention.
On Wednesday I used one to turn my latest essay into a week of Instagram posts. The skill is called the promo kit, and it knows my colors, my fonts, which art to use, which sizes Instagram wants, and that nothing it makes ever gets posted without me. It built seventeen images in one pass. I looked at the Stories and said the frames were selling the wrong thing: they led with the essay’s definition, and the story of what happened was more interesting. Then I said six frames was too many. Four. Both notes took a sentence each. The library of skills I have built since May does not exist because I learned to program. It exists because I got tired of saying the same thing twice.
I have 46 skills in Claude Code as of October 15, 2026. I built 31 of them by talking, in plain sentences, inside a Claude Code session. The other fifteen I installed or adapted from people who build these things for a living. This guide is how the 31 got made, what goes in one, and how to start yours tonight.
The thirty-second answer
✶ The thirty-second answer
A skill is a job you explained once, written down so you never explain it again. When you notice you have described the same task to Claude Code three times, the steps, the order, the place it always goes wrong, ask Claude to write that explanation into a skill. Keep what is always true about you in your CLAUDE.md, keep single facts and corrections in memory, and put anything with steps into a skill. Then, every time the job runs and you correct something, have the correction written into the skill’s Lessons section. The skill gets better on every run. You do not need to code. You need to notice repetition.
What a skill actually is
A skill is a folder. Inside the folder is a file called SKILL.md. The file starts with two lines that matter more than anything else in it: a name, and a description of when to use it. Everything after that is instructions, written the way you would brief a sharp new hire on their first day.
The shortest skill I own is 31 lines. It is my literary editor, Heron, which reads my memoir chapters and fiction. Trimmed for length, it looks like this:
Read it as a job description. The description at the top is the part Claude reads at the start of every session, so it says what the job is and the words I actually use when I want it: “read this,” “line notes,” “workshop this.” The procedure is the order things happen in. The hard rule at the bottom is the line the skill never crosses, and for Heron that line is the whole point. An editor who rewrites your sentences is a ghostwriter, and I did not want one.
A skill folder can also hold files the instructions point to. My promo kit carries the two small programs that render the images and build the review page. The skill that fixes the moving picture on my homepage carries the one script that rebuilds it. You do not write those files either. You ask for them in the session that writes the skill, and the skill tells Claude to use them.
Where skills live, and how Claude finds the right one
There are two places to put a skill, and the choice is about reach.
Thirty-seven of mine are global, in the first folder, because they are about me: my email voice, my LinkedIn voice, my design taste. Nine live inside my personal-brand folder, because they only make sense there. The promo kit knows where my essays are published. A session in a client’s folder has no reason to know that.
Claude does not read all 46 skills at the start of a session. It reads each skill’s name and description, a few lines apiece, and opens the full file only when the job in front of it matches a description. Anthropic calls that progressive disclosure, and it is why a big library costs almost nothing to carry around. It is also why the description is the most important thing you will write. A skill whose description does not sound like the way you ask for the job will sit in its folder and never get used. You can also call any skill by name, with a slash: /promo-kit.
Skill, memory, or CLAUDE.md?
Claude Code gives you three places to put what you know, and most of the early mess in my setup came from putting things in the wrong one.
Three places to put what you know. A thin one that is always open, a stack of single facts, and the jobs with steps.
| Put it in | When it is | Example from my setup |
|---|---|---|
| CLAUDE.md | Always true, in every session in this folder | Who I am, how my folders are organized, the voice rules nobody is allowed to break |
| Memory | One fact, or one correction | My site says “essays,” never “letters.” The newsletter runs on Kit. |
| A skill | A job with steps that you will do again | Resend one newsletter issue to a reader who found it in spam |
The test I use: if it has an order, it is a skill. “My site says essays” has no order. It is one fact, and it lives in one small memory file, one of 119 in my personal-brand folder. Resending an issue to a single reader has an order: find their email, find the issue, make a one-person copy, write the note, check it, leave it for me to send. Each step has a way to go wrong that I learned the hard way, so the steps and their traps live in a skill.
The other test is cost. Whatever is in CLAUDE.md loads in every session, whether the session needs it or not, so it should stay short. Mine is 53 lines for the whole personal-brand folder. A skill only loads when its job comes up, so it can be as long as the job needs. The longest one I built is 629 lines, and it is long because it has been corrected 22 times.
Not every repeating job wants a skill. My interview series, The Constellation, runs on two documents instead: an operating doc and a craft file, 227 lines between them. Every profile is a different person, so the documents hold the rules of the craft and the session does the rest. When the work is mostly judgment, I write down the judgment. When the work is mostly steps, I write down the steps.
The five kinds of skills in my library
After five months, most of my 31 fall into five kinds. Naming the kind helps decide what goes in one.
| Kind | What it holds | Example |
|---|---|---|
| A voice | How I sound in one place, and what I have rejected | linkedin-voice: short paragraphs, em-dashes, no engagement bait, and two dated notes on drafts I threw out |
| A pipeline | A multi-step production with a fixed order | promo-kit: one essay in, images and captions and a review page out |
| A fix | A repair, with the mistakes it must never repeat | loop-motion-fix: measure the homepage animation first, never regenerate it, verify playback on a real phone width |
| A partner | A role, with the line it never crosses | heron: reads and gives notes, never writes my sentences |
| An errand | A small job that used to take an afternoon | resend-letter: one issue, one reader, two drafts left for me to send |
The fix kind surprised me most. My homepage has a slow animation of light moving along an arc, and in August it took me twelve versions to get it right. The skill that came out of those twelve versions opens with a section called “Never do these,” and every line in it is a version that failed. When the animation drifts now, the fix is a procedure, not a week.
Every skill needs a place to stop
The most important line in most of my skills is the one that says where the skill stops and I start.
- The promo kit: “Never post.” It ends at a review page and a folder of files.
- The email skill: “this skill NEVER sends email.” It leaves drafts in my inbox.
- The resend skill: “Nothing here sends anything.” Two drafts, and I click both.
- The homepage fix: a test version only, and the live site “ONLY on Joe’s explicit ‘ship it.’”
A skill makes Claude faster at a job, which means it also makes Claude faster at the wrong version of the job. The stop line is how the speed stays useful. Write it into the skill on the first day, in plain words, near the top. The machine does the part I can’t. The part with my name on it waits for me.
How a skill gets better: the Lessons section
A skill is not done when it works. It is done when it stops surprising you, and that takes runs.
The recipe box. Every run adds a card.
At the bottom of my working skills there is a section called Lessons. After each run, the correction from that run goes in, dated, in a sentence or a paragraph. The video skill that turns still images into short films has 22 of them. One reads, more or less: the browser tool I use to check pages is the wrong tool for checking video, because it reports the tab as hidden and the video never loads, so use a real headless browser instead. That lesson cost an evening once. It has cost nothing since.
The lessons are not only technical. My LinkedIn voice skill holds the day I rejected a draft framed as “my weekend experiment” and asked for the industry frame instead: what the best people in the field say to do, then my own numbers as proof. That note now rides along on every post of that kind.
The promo kit has one lesson so far, from its first run in September. It is about to get its second. Wednesday’s two notes, tell what happened instead of what it means and keep Stories to four frames, are exactly the kind of thing I would otherwise say again next week. The routine is one sentence at the end of a run: “Add what we learned to the skill’s Lessons.” The skill gets better on every run, and you never have to remember to say it twice.
Other people’s skills
Fifteen of my skills came from someone else. Thirteen I installed whole, mostly design tools, from public skill collections, including Anthropic’s own examples. Two I adapted: a pair of LinkedIn skills, released under an open license, for sorting the comments on a post and auditing which posts worked. I kept their procedure and pointed their voice at my own voice file, so they sound like me and not like the person who wrote them.
Read a skill before you install it. A skill is instructions that run with whatever permissions your session has, and a skill from a stranger is a stranger’s instructions. Most are fine. Reading one takes five minutes, and it is also the fastest way to learn what a good skill looks like.
Your first skill, tonight
Pick a job you have explained to Claude Code at least twice. Do the job once more, in a session, start to finish. Fix whatever goes wrong as it goes wrong. Then, before you close the session, paste this:
Read what comes back the way you would read a new hire’s notes on their first week. Fix the description first: if it does not sound like you asking for the job, the skill will never be used. Then save it, open a fresh session, and ask for the job in your own words. If the skill shows up and does the job your way, you have one.
The file it writes will look something like this, and you can also write one by hand:
What I’d tell you on day one
- Wait for the third time. A skill written before you have done the job twice is a guess about the job. The third explanation is the one worth keeping.
- The description is the skill. Write it in the words you actually use. Claude matches on those words.
- One job per skill. When a skill starts doing two jobs, split it.
- Point, don’t copy. If a fact lives somewhere else, the skill should say where, not repeat it. My ghostwriting skill holds no voice rules at all; it points at each person’s voice file, so one correction updates every future draft.
- Write the stop line first. Then everything else.
- Lessons after every run. One sentence is enough.
One essay, every Sunday morning, from the human in the loop.
Questions I get asked
Do I need to know how to code to build a Claude Code skill?
No. A skill is a text file of plain instructions with a short header. I built 31 of my 46 by describing a job inside a Claude Code session and asking Claude to write it into a skill. When a skill needs a small program, the same session writes that too.
What is the difference between a skill and a CLAUDE.md file?
CLAUDE.md loads in every session in its folder, so it holds what is always true and should stay short. A skill loads only when its job comes up, so it can hold a long procedure. The test I use: if it has an order, it is a skill.
Where do Claude Code skills go?
In ~/.claude/skills/<name>/SKILL.md for skills every project can use, or in .claude/skills/<name>/SKILL.md inside one project for skills that only make sense there. Thirty-seven of mine are global and nine live in my personal-brand folder.
How does Claude know which skill to use?
At the start of a session Claude reads each skill's name and description, and opens the full file only when the job in front of it matches a description. You can also call a skill by name with a slash, like /promo-kit. A skill whose description does not sound like the way you ask for the job will rarely be picked.
How many skills is too many?
Because only names and descriptions load up front, a big library costs very little. The real limit is overlap: two skills with similar descriptions compete for the same request. Keep one job per skill and split a skill when it starts doing two.
Is it safe to install skills other people wrote?
Read one before you install it. A skill is a set of instructions that runs with your session's permissions, so a stranger's skill is a stranger's instructions. Most are fine, and reading them is the fastest way to learn what a good skill looks like.
— Joe
