A Claude Code skill is just a markdown file (and most of them are garbage)

TL;DR: A Claude Code skill is a markdown file with a name and a description. Nothing more – no compiler, no proprietary format, nothing to rent. That’s the demystification. The anti-hype half: I ran a well-built downloadable writing skill head-to-head against the system I built myself, across nine real blog posts, and the generic one contributed real things while losing everywhere that mattered. Somebody online can sell you the standard moves of a craft. They can’t sell you what makes your expertise yours.

What is a Claude Code skill?

A Claude Code skill is a markdown file with a name and a description. When Claude decides the current task matches the description, it reads the file and follows the instructions inside. That’s the entire mechanism.

If I opened one of my skills in a text editor and deleted a paragraph, Claude would stop doing whatever that paragraph told it to do, and nothing else would break. No compiler, no vendor, no install beyond putting a file in a folder. Skills are one piece of the working setup, and they’re the piece with the most mystique and the least mystery.

Is it worth it to buy skills?

I think no, because the framing is a category error: a skill isn’t software, it’s a documented practice – how somebody does something, how they work, written down in a form an AI can follow. Software you can evaluate: it does the same thing for everyone, and you can see what it does before you rely on it. A stranger’s documented practice is different. You have no way of verifying how that person actually works, which means you have no way of knowing the quality of what you bought.

I once saw somebody selling a competitor-research skill – it wasn’t cheap. It does a bunch of web scraping and compiles the outcome into a massive wall of text. That looks impressive in the promo video, where somebody holds up a cute picture of the report. Then I think: my God, reading this massive wall of AI-generated text, produced by somebody else’s tool with no understanding of the context of my business – it’s pulling generic information off the web.

Downloaded skill vs. your own system: the experiment I didn’t plan to run

I didn’t set out to run a comparison. I was working with my AI on a batch of blog posts when I noticed it had loaded a skill I didn’t recognize – a well-built, downloadable professional writing skill with an SEO framework built in – and it was following it. So afterward I asked: wait, did you use that skill, or my skill? We worked out that it had used the other one. Then we did the analysis retrospectively: what’s in that skill, and how does it compare to my own system – a writing playbook, a voice guide, and per-post briefs I’d written myself?

It turned out my system was better. It also turned out my system was missing a few things – things I do anyway, that had never been “skillized.” Both halves of that result are below.

What the generic skill got right

It wasn’t nothing, and pretending otherwise would make this a rant instead of a result. Three real contributions across nine posts:

1. Meta-element discipline. Every post ended with a title tag under 60 characters, a meta description under 155, alt text as a descriptive sentence. My playbook said nothing about meta elements. I add them anyway – but it isn’t part of my formal skill, so there’s always the danger that I forget, or have to go look up how long a title tag is supposed to be again.
2. Heading hierarchy hygiene. Never skip levels, never leave a lonely H3 floating. Small, unglamorous, consistently correct. My skill doesn’t contain this one either. I’d catch it in editing – I absolutely hate lonely headings – but knowing a rule and writing it down are different things, and what isn’t written down invites inconsistency.
3. The instinct to finish the draft. My system stops and asks when judgment is needed – load-bearing for the big calls – and the generic skill counterbalanced it with an instinct to deliver a complete draft instead of pausing at every minor ambiguity. One qualifier: how much an AI stops to ask also depends on which model you’re running and what rules it’s under, so the same two skills can strike a different balance on a different day.

Why does a custom skill beat a generic one?

If you’re an expert in an area, your custom skill is going to beat a generic one, because you know everything about it. A skill I use in my own work can contain things a generic skill structurally cannot:

1. Voice. The generic skill’s entire voice model is “read the project docs.” It has no opinion about which exact seventeen words are banned. My voice guide is built from verified quotes of how I actually talk. A generic skill cannot contain a person.
2. Hedge direction. The generic skill treats hedging as uncertainty management: add “may” or “often” when unsure. My rule runs the opposite way – my hedges are deliberate precision markers that must be protected from deletion. Same words, opposite editorial force. A generic tool would confidently “punch up” exactly the words my credibility depends on.
3. Receipt fidelity. Generic rule: don’t invent facts. House rule: every first-person claim must trace to a specific source line or get flagged for my review. That’s not fact-checking. That’s biography protection, and generic skills don’t have the category because they don’t model a specific human’s lived experience as the product.
4. The receipt register. One anecdote anchors in one post; other posts may reference it but not retell it. Generic skills optimize one page at a time and have no concept of a portfolio cannibalizing its own material.
5. The feedback loop. Every draft ends with a note on the tradeoffs made, so I can steer the next batch. Generic skill: deliver and done. House system: deliver and learn. (The rules themselves come from captured corrections – that mechanism is Your frustration is data.)
6. Risk model. No client names, no domain specifics, abstraction rules for what I’m not allowed to say. A generic skill doesn’t know your NDAs exist.

The lesson

Anybody can make a skill. Claude will make you one – it ships with a skill for exactly that (mine is called skill-creator). So a skill somebody’s selling is only worth something if that person has real expertise in the thing and actually wrote that expertise down. And a skill that scrapes the web and synthesizes a report? I’d call that inspiration: you can ask Claude to build you the same thing for free, and inject your own expertise into the process while you’re at it.

Your own system encodes the only part that differentiates you: your voice, your receipts, your audience, your risks. The generic skill is a competent stranger; the house system is institutional memory.

That’s also why these AI-drafted posts are still mine: the system doing the drafting is made of me.

Things I borrowed anyway

Even a competent stranger might have something to contribute. From the generic skill, into my playbook:

1. Meta elements as a mandatory final-pass step.
2. Heading hierarchy as an actual rule, not a vibe.
3. Extractable closing sentences per section – adopted with a leash: the closer must make a new claim, never recap.
4. Schema flags as a note for the publishing pipeline.
5. Conversion mode, a whole gap in my system. Mine was search-mode only. The generic skill carried a second mode for readers who arrive warm, from an email or a video: name their felt situation, honor what they’ve tried, reframe, show what’s possible, prove it, ask once. When my newsletter landing page gets built, I’ll use that arc – rewritten in my register, but the shape is stolen.

It’s early days for all of this, and everybody’s learning. The nice thing about a system made of text files is that it’s all readable: you can look at what other people are doing, see how their skills work, and use them as inspiration for your own. Be a little careful about downloading random stuff from all over the place and letting it run. But you can read a skill before you trust it – it’s a text file. Read what it says, then build your own version.

Should you download Claude skills or write your own?

Three questions sort it.

What is your ambition? If you’re starting from zero and want something better than you’d come up with on your own, absolutely download a skill. If your work is distinctive and you have expertise, the generic skill is going to lose – so if you do start from a download, keep updating it with your own expertise until it’s yours.

Have you done the thing manually enough to know what you’d want a rule for? If yes, write your own – you know the specifics that make it yours. If not, download one to learn the shape, then rewrite it.

Will anyone read the output and know it’s you? If yes, your voice needs house-level treatment. If no – internal notes, throwaway analysis – generic is fine, and cheaper than caring.

Writing your own processes down as skills is exactly the kind of thing I build with people, on their real work.