I've written around twenty Claude Code skills in the last few months. Some are obvious — read my Slack, query my analytics, transcribe a YouTube video. Some are stranger — distill my own writing style from past WhatsApp messages, audit a Mac for disk hogs, run a daily cross-project digest. They're all in claude-skills.

A few people have asked me what a skill actually is, when one earns its place over a prompt or a CLAUDE.md note, and how I structure them so Claude reaches for them at the right moment. This is the version I wish I'd had when I started.

What a skill actually is

A Claude Code skill is a folder with a SKILL.md file at the root, plus whatever supporting scripts, references, or assets it needs. The SKILL.md has YAML frontmatter — name, description, and a list of trigger phrases — followed by the body, which is regular markdown that Claude reads when it decides the skill is relevant.

That's it. There is no runtime, no plugin loader, no build step. The skill is a Markdown file Claude can find and read. The frontmatter helps it decide whether to read.

If you've ever written a CLAUDE.md for a project, you already know the format. A skill is that pattern formalised: a CLAUDE.md scoped to a task rather than a codebase, plus the metadata that lets Claude pick it up without you typing the path.

Skills vs prompts vs CLAUDE.md

There are three layers in a Claude Code project and I see people confuse them all the time.

Prompts are what you type in the chat. They live in the moment. They're cheap to write and cheap to throw away. If you find yourself typing the same sentence twice, you're probably in skill territory.

CLAUDE.md is the codebase's constitution. It says how this repo wants to be worked on — coding conventions, what tests to run, what to avoid. It loads every session, automatically. Use it for project-specific facts that should never need restating.

Skills are task-shaped. They contain how to perform a specific recurring action — search Slack, ship a release, audit a PR. They live in your home directory or a shared repo, and Claude pulls them in on demand based on the description and triggers in the frontmatter. They're portable across projects.

The boundaries get blurry. A useful heuristic: if the content describes the project, it belongs in CLAUDE.md. If it describes a task, it belongs in a skill. If it's a one-off question, it's a prompt.

When a skill earns its place

I write a skill when three things are true at once.

The task recurs. I've done it more than twice and I'll do it again. Once-off work doesn't earn the time to write a skill — it earns a prompt.

The right shape isn't obvious. Without guidance, Claude would pick a workable but suboptimal approach. The skill encodes the decision I want it to make — which CLI to reach for, which API to hit, which thing to do first.

There are footguns. Steps that look reasonable but break in specific ways. Race conditions, rate limits, ordering issues, surprising defaults. The skill is where I document those once and never explain them again.

If two of those three are true, a skill is probably worth the half-hour. If only one is true, it's probably still a prompt.

A concrete walkthrough — mailchimp-copy-style

Not every skill wraps a CLI. One of the ones I reach for most is mailchimp-copy-style — a house copy guide adapted from the Mailchimp Content Style Guide that tells Claude how to write every user-facing string in my apps.

The frontmatter triggers are phrases like "write copy," "button text," "error message," "empty state," "push notification." Whenever I'm touching UI text, Claude loads the skill automatically.

The body opens with four standards — clear, useful, friendly, appropriate — then separates voice (stays constant) from tone (shifts with context). There are concrete sections for buttons, error messages, empty states, onboarding, push notifications, and even App Store copy. Each section has do/don't pairs with examples.

It's about 240 lines. No shell commands, no API calls. Just prose that shapes how Claude writes. When I ask "write the empty state for the shopping list," Claude doesn't produce generic placeholder text — it follows the voice I codified once.

I have a similar one called kole-design-tips — a UI/UX playbook distilled from a design tutorial series. It covers typography scales, spacing grids, color ratios, dark mode palettes, dashboard layout, mobile patterns, and a "vibe-coded smell test" checklist. When I'm designing a screen, Claude loads the design skill and the copy skill together. The copy comes out sounding right and the layout follows the house rules.

These two are my most-used skills, and neither of them touches a terminal.

Patterns I use

A few patterns have crystallised across the twenty-odd skills I've written.

Lead with the mental model. The first paragraph of every skill body is a short, accurate description of how the underlying thing works. Two sentences. The rest reads better when Claude has that frame.

Decision tree, not a wall of options. "If you want X, do A. If you want Y, do B. Default to A." Claude follows trees well. It does less well with paragraphs of equally-weighted options.

Show the exact command, parameterised. Claude is excellent at filling in placeholders. It's much less reliable at constructing a command from a description.

Name the failure modes. A "Gotchas" section at the bottom saves more time than any other section. Document the silent failures and the wrong-looking-but-correct behaviour.

Keep it short. If a skill is longer than 400 lines, it wants to be split. Long skills get diluted; short skills get followed.

How I ship and share them

The repo at github.com/johnkueh/claude-skills is a plugin in the Claude Code sense — a directory of skills with a manifest at the root. Anyone with Claude Code can install the plugin and inherit the whole library, the same way they'd install an npm package.

I keep mine public for two reasons. First, half of them are useful to anyone with the same domain — wacli, slack-search, notion-page, system-disk-cleanup aren't specific to me. Second, public ones get edited better. When something is in a repo with a README and a license, I'm more honest about the edge cases and less likely to leave half-finished thoughts in the body.

The other useful pattern: skill folders can contain executable files alongside the markdown. A skill that wraps a tool can ship the tool. Mine often include a cli.py or a doctor.sh that the skill body references by relative path. Claude finds them automatically because they sit next to the SKILL.md.

When not to write a skill

Some things look like skills but aren't.

One-off shell incantations. If you only ever need the command once, just paste it into the chat. The skill cost isn't worth it.

Anything that's already a good CLI. If the underlying tool has a clear --help and obvious flags, Claude can drive it without a skill. Skills earn their place where the tool is implicit, the workflow is non-obvious, or the failure modes need documenting.

Style guides that span the whole project. Those belong in CLAUDE.md. A skill is for a specific task. A CLAUDE.md is for the project's default conventions.

Long-running stateful workflows. Skills are good at telling Claude how to do something. They're not great as workflow engines. If the work has multiple human-in-the-loop steps, a skill plus a CLI is usually better than a giant skill alone.

What I'd do if I were starting today

Pick the two tasks you find yourself describing to Claude the most. Write each one as a 100-line skill in a single folder under ~/.claude/skills/. Use them for a week. Iterate the descriptions and the gotchas based on what you actually hit. After two weeks, decide which to keep, which to split, and which to delete.

The library compounds quickly. The first skill takes thirty minutes; the tenth takes ten. By the time you have twenty, Claude reaches for the right one without you having to prompt it.