A Claude Code skill is a text file of instructions, saved in a folder, that Claude reads when it fits what you asked for. That’s the whole thing. No code, no install, no plugin. Mine are markdown files I wrote in plain English, and the one below is 22 lines you can copy and use today.
Part 3 of Claude Code for Bloggers. Start with Part 1 and Part 2 if you haven’t.
This post contains affiliate links. If you sign up through one, I earn a commission at no extra cost to you. I only point to tools I actually use or would recommend.
Four things a Claude Code skill is not
The word skill is doing a lot of damage here. It sounds like software. So before the definition, four things to put down:
A skill is not a plugin. Nothing gets added to Claude Code. You’re leaving it a note.
A skill is not code. It’s markdown, which is the same plain text you write a blog post in. If you can write a bulleted list, you can write a skill.
A skill is not something you install. There’s no download, no package, no command to run. A file appears in a folder and it starts working.
A skill is not an app. It doesn’t run on its own or sit in the background. It does nothing at all until you ask for something it fits.
What it is: a set of instructions you got tired of retyping, parked somewhere Claude will find them.
What’s inside a Claude Code skill file?
A skill is one file called SKILL.md inside a folder named after the skill. That file has two parts.
The top part, between two lines of three dashes, is the frontmatter. It’s a couple of lines that tell Claude when this file is relevant.
The bottom part is the instructions. Written to Claude, in your own words, the way you’d explain the task to a person doing it for you the first time.
That’s it. Two parts, one file.
A skill you can copy right now
This one writes meta descriptions. Every post needs one, they’re fiddly because of the length limit, and the rules fit in six bullets. Copy the whole thing:
---
name: meta-description
description: Use when I need a meta description for a blog post, or when I say "write the meta", "meta description", or "SEO description" for a post.
---
# Meta description
I'll give you a post as a URL, a file, or pasted text. Write three meta description options for it.
Every option must:
- Be between 140 and 160 characters, spaces included
- Put the main keyword in the first half
- Say what the reader gets, not what the post "explores" or "covers"
- Be one complete sentence or two short ones, so it doesn't read as cut off
- Avoid discover, unlock, dive into, ultimate, and game changer
Print each option on its own line with its exact character count in brackets after it.
Then pick the one you'd use and say why in a single line.
If you can't tell what the main keyword is, ask me before writing anything.Twenty two lines, and seven of them are blank. Nothing in there is code. Every line is a sentence I’d say out loud to a person.
The same file, line by line
What each part is doing, because once you can read this file you can write your own:
The three dashes. They mark the start and end of the frontmatter. Claude reads what’s between them differently from the rest. Keep them.
name. The label that shows up when Claude lists what it has. Useful to know: for a skill you save yourself, this does not set what you type to run it. The folder name does that. My file lives in a folder called meta-description, so I type /meta-description. If the two disagree, the folder wins.
description. The most important line in the file, and the one that decides whether any of this works. Claude reads every skill’s description all the time, and it reads the rest of the file only when the description looks like a match for what you just asked. Mine lists the actual phrases I’d type. Not “helps with SEO.” The words I really use.
The heading and the instructions. Everything below the frontmatter only gets read once the skill is actually running, so there’s no cost to being specific. Notice what the rules do: they give numbers instead of adjectives. “Between 140 and 160 characters” can be checked. “Concise” cannot.
The last line. If you can't tell what the main keyword is, ask me before writing anything. A skill can tell Claude to stop and ask. That single line has saved me more bad output than all the others combined.
Where do you save a skill without touching a terminal?
You do not have to make the folder yourself. Paste the file into Claude Code and say:
Save this as a skill called meta-description.
Claude makes the folder and writes the file. Then it lands in one of two places, and the difference matters:
| Where it lands | Path | Available in |
|---|---|---|
| Personal | ~/.claude/skills/meta-description/SKILL.md | Every project, everywhere you work |
| Project | .claude/skills/meta-description/SKILL.md | Only that one project |
For writing skills you want the personal one, so it follows you into every folder. Say “save it as a personal skill” if you want to be sure.
One thing to know the first time. Claude Code notices new skills straight away, so it’s usually ready in the same session. But if that skills folder didn’t exist before you started, Claude Code isn’t watching it yet, and your brand new skill won’t show up until you quit and reopen. If your first one seems to do nothing, restart before you assume you wrote it wrong.
What happens the first time a skill fires?
You open Claude Code, paste a draft, and type “write the meta for this.”
Claude spots that the description matches, reads the rest of the file, and gives you three options with the character counts after them, then names the one it would pick. You didn’t type a slash command. You didn’t explain the rules. The file did that.
When I ran the file above against my blog post checklist skill post, it came back with options at 151, 153 and 148 characters. All three inside the limit on the first try, because the limit is written down instead of remembered. Then I paste the winner into Rank Math and move on.
You can also run it on purpose by typing /meta-description. Same file either way.
Three ways a skill goes wrong
All three of these have happened to me.
| What went wrong | Why | The fix |
|---|---|---|
| It never fires | The description was vague, so Claude never saw a match | Write the literal phrases you’d type, like the ones in the example |
| It does too much | One giant skill tried to handle five jobs and got the wrong one | One skill, one job. Split it |
| It fires when you don’t want it | The description was so broad it grabbed unrelated work | Name what it’s not for, right in the description |
The first one is the most common by a distance, and the most confusing, because a skill that never loads looks exactly like a skill that doesn’t work. Mine sat there doing nothing for a while, and the file was fine the whole time. The description was the problem.
So when you write yours, spend your time on that one line. Everything else is just instructions, and instructions are easy to fix later.
Two details that help: Claude only reads about 1,500 characters of your description, so put the important part first. And if you want to list a lot of trigger phrases, you can add a second line called when_to_use under the description and put them there. It gets read right along with the description, so it’s the same budget, just tidier to look at.
If you’d rather answer a few questions than start from a blank file, I built this to do exactly that. Fill it in and it writes the whole SKILL.md for you, and it grades your description as you type so you can see whether it would actually fire.
You don’t have to write them by hand forever
There’s an official skill-creator from Anthropic that will draft skills for you and help you test whether the triggering works. It’s a real tool and I use it.
I’d still learn the anatomy first. Not out of principle. Because when a skill misfires, and it will, the fix is one line in a file you have to be able to read. Ten minutes with the example above buys you that.
If you’d rather not learn this alone in a folder, AI Automation Society Plus is the Skool group where I keep up with n8n and Claude Code, and people post what they’re building most days.
Frequently asked questions
What is a Claude Code skill?
A text file of instructions, saved in a folder, that Claude reads when it matches what you asked for. No code, no install. You write it in plain English.
Is a Claude Code skill code?
No. It’s a markdown file, which is plain text with a few formatting marks. You write it in the same English you’d use to explain the task to a person.
Where do Claude Code skills live?
Personal skills go in ~/.claude/skills/<name>/SKILL.md and work in every project. Project skills go in .claude/skills/<name>/SKILL.md inside one project folder and only work there.
Do I have to type a slash command to use a skill?
No. Claude reads every skill’s description and loads the ones that match what you asked for. You can type /name to force it, but a well described skill fires on its own.
How long should a skill be?
As short as it can be while still being specific. The example here is 22 lines, and only 15 of them have anything on them. Long reference material is fine too, because the body only loads when the skill runs.
Can one skill do several jobs?
It can, but it works badly. A skill covering five tasks tends to fire for the wrong one. One skill, one job.
A tool I built
Side Hustle Garden
Log every side hustle payment and watch it knock out your monthly bills, smallest first.
Plant your first dollar →I run an affiliate program on the tools I build. Approved affiliates earn 20% on what their referrals pay, for up to a year. US only for now. See the program →
Related reading
- Stop Pasting Your Style Guide Into Every New Chat
- Turn Your Blog Post Checklist Into a Claude Code Skill
- Ways to Customize LLM Voice to Match Your Personal Brand
Try it yourself
A Claude Code skill is a text file you write once so you stop explaining the same thing every session, and the meta description one above is a fair first try because you’ll know within a minute whether it worked. Copy it, save it, run it on the last post you published.
Then steal the other two. The voice skill keeps your style rules out of every new chat, and the checklist skill audits a finished draft and hands back a fix list. Both are printed in full, same as this one, and three files is enough to feel the difference.
That’s Part 3 of Claude Code for Bloggers. Subscribe if you want the rest of the series.
