How to Write a Claude Skill That Actually Works
How to write a Claude skill that actually works comes down to one thing most guides skip: the skill has to carry your judgment, not just your instructions. Anyone can tell Claude to write a professional quote. A skill worth keeping knows what to refuse, what to ask for, and what to never leave out.
I have built a dozen of these now, for trades, for SEO work, for freelancers chasing invoices. Here is what separates the ones people use every day from the ones that get installed and forgotten.
What a Claude skill actually is
A skill is a plain text file, written in Markdown, that Claude reads and follows automatically. It has two parts: a short block of frontmatter at the top that tells Claude what the skill is and when to use it, then the instructions themselves.
The bones look like this:
---
name: quote-builder
description: Turns rough job notes into a professional written quote. Use whenever the owner describes a job and needs an estimate, quote, or bid written up.
---
# Quote Builder
You turn job notes into quotes that win work.
## What a quote needs
...That is the whole format. Anthropic publishes the official documentation for skills if you want the full specification. But the format is the easy part. The file being good is the hard part.
The description line that decides whether it ever runs
The description in your frontmatter is the most important sentence in the file, and almost everyone writes it wrong.
Claude uses that description to decide whether the skill applies to what you just asked. A vague description means the skill sits there unused while Claude answers from scratch. So write it with the actual words people say, not a job title.
Weak: A skill for writing quotes.
Strong: Turns rough job notes into a professional written quote. Use when someone describes a job and needs an estimate, quote, or bid written up, including voice-to-text rambles like gutter job on Maple, two story, 180 feet. Trigger on write up a quote, estimate for, bid this job, send them a price.
The second one fires when you need it. The first one does not. Put the real trigger phrases in, including the messy ones.
Write judgment, not tasks
This is the difference between a skill and a prompt with a filename.
A task instruction says what to produce. A judgment instruction says what to protect. When I wrote a quoting skill, the useful lines were not about formatting. They were rules like: never invent a price the owner did not give you. If the owner gives a range, present the top of the range, never the bottom, because quoting low and climbing is how trust dies. Always include what is not included, because that line is the owner’s legal friend.
None of that is about writing. It is about knowing where the work goes wrong. Ask yourself: what does a beginner in my field get wrong that I no longer get wrong? Those answers are the skill. Everything else is formatting.
Give it voice rules, including the banned list
Claude writes competently by default, which is exactly the problem. Competent and generic sound the same.
Tell the skill how to sound, in specifics. Short sentences or long ones. Contractions or not. Whether to open with the answer or with context. Then, more useful than any of that, give it a banned list. Phrases like look no further, in today’s fast paced world, we go above and beyond, and any sentence starting with in conclusion. A skill that knows what never to write produces cleaner output than one that only knows what to write.
If you have examples of your own writing, put a paragraph or two straight into the file. Claude matches patterns better than it follows adjectives.
The memory file: what separates a skill from a system
Here is the part most skill guides leave out entirely, and it is the one that changes everything.
A skill by itself starts fresh every time. It knows how to write a quote, but not your rates, your service area, or the fact that you never work weekends. So you re-explain those things constantly, which is the exact problem skills were supposed to solve.
The fix is a plain Markdown file that lives alongside the skill and holds the specifics. Call it whatever you want. Then add two instructions to the skill itself:
- Read it first. Tell the skill to check for the file before doing anything, and use what is in it.
- Write to it after. Tell the skill to append what it learned, in short lines, under the right heading.
Now the tenth quote takes seconds instead of minutes, because the skill already knows your pricing rules and how you sign off. The tenth review response sounds more like you than the first one did. And you own the file, so nothing is trapped in a platform.
One warning learned the hard way: the filename in your instructions has to match the file you actually keep, character for character. A skill looking for business-profile.md will quietly create a blank one if your file is named business-profile-starter.md, and nothing will error. It will just silently forget everything.
Test it on real work, then fix the file
Do not test a skill on a made up example. Pull something real from last week, run it through, and read the output like the person who receives it.
When something comes out wrong, resist the urge to fix that one output. Fix the file instead. Tell Claude what missed and ask it to update the skill going forward. You are not correcting an answer, you are improving the instruction manual for every answer after it. Three rounds of that and the skill is genuinely yours.
Mistakes to avoid when you write a Claude skill
- Too broad. A marketing skill does nothing well. A skill for writing Google Business Profile posts for home service companies does one thing well.
- No trigger words. Covered above, and it is the most common reason a good skill never runs.
- All format, no judgment. If the file only describes structure, you built a template.
- No memory file. You will re-explain your business forever.
- Twenty skills, none finished. One working skill beats a folder of drafts. Ship one, use it for a week, then build the next.
If you would rather have this done for you, that is our whole business. The ready made stacks are built this way, memory files and all, and custom stacks take your process and turn it into skills your team can run.
How to write a Claude skill, in short
- Write a description packed with the real phrases people say, so it fires when you need it.
- Put your judgment in, not just the steps. What to refuse, what to protect, what never to leave out.
- Give it voice rules and a banned phrase list.
- Pair it with a memory file it reads first and writes to after.
- Test it on real work from last week, then fix the file instead of the output.
- Ship one and use it before building the next.
Frequently asked questions
How long should a Claude skill be?
Most good skills land between 100 and 300 lines. Long enough to carry real judgment and voice rules, short enough that every line earns its place. If it is under 30 lines, it is probably a prompt. If it is over 500, it is probably two skills.
Do I need to know how to code to write a Claude skill?
No. A skill is written in plain English inside a Markdown file. The only technical part is the small frontmatter block at the top, and you can copy that structure from any existing skill.
Can Claude write the skill for me?
Yes, and it is a good starting point. Describe the job, paste an example of the output you want, and ask for a skill file. Then do the part Claude cannot do for you: add the judgment rules from your own experience, and test it on real work.
Where do I put the skill file?
In the Claude apps you attach the skill file in a chat and save it. In Claude Code you place the folder in your skills directory. Both read the same Markdown, so one file works in either place.
How is a skill different from a Claude Project or a custom GPT?
Projects and custom GPTs keep your instructions inside one tool. A skill is a portable file you own, it works across sessions, and paired with a memory file it accumulates knowledge about your business instead of starting over every conversation.
