What Claude Skills actually are (and why most people are getting them wrong)

Most builders we've talked to think Claude Skills are saved prompts.

You write down a workflow. You name it. You can call it again later. End of feature.

That mental model is wrong, and it's missing the part that makes Skills actually useful. Skills aren't "prompts in a file." They're a way to teach Claude reusable workflows that barely cost anything to keep around — Claude only loads them when they're relevant. They live as folders on your computer. They have rules about who sees them: just you, your whole team, or everyone in your company. And they don't move between Claude.ai, Claude Code, and the Claude API the way you'd expect.

If you're already using Claude or Claude Code and you're wondering whether to bother with Skills, this is the explainer we wish existed when we started.

What's actually in a Skill

A Skill is a folder on your computer. The folder contains a single file called SKILL.md, and optionally anything else — reference notes, templates, helper scripts, examples, sub-folders.

The SKILL.md file is where the magic happens. It has two parts.

Part 1: a label at the top. A few lines in a structured format that tell Claude what the skill is for. It looks like this:

---
name: brand-voice-editor
description: Edit copy to match the Agent Shortlist brand voice
when_to_use: When the user asks to edit, review, or rewrite copy for the website
---

The description and when_to_use lines are how Claude decides when to reach for this skill. We'll come back to this.

Part 2: the instructions. Plain English (or markdown formatting if you like) telling Claude how to do the workflow. Examples. Rules. Things to avoid. Whatever you'd write down for a colleague learning the same task.

That's it. A skill is two things: a label that tells Claude when to use it, and a body of instructions for how to do the work. Everything else — the templates, supporting files — only loads when Claude needs them.

The thing that makes Skills actually useful

This is the part most explainers get wrong, and it's the reason Skills aren't just "prompts in a file."

Claude has a cost ceiling: every conversation can only hold so much information before it starts forgetting earlier parts. The technical name is the context window, but the practical version is — Claude has limited attention, and everything you give it eats into that attention.

Skills solve this with three loading layers:

• Always loaded: just the label. The description and when_to_use lines from the top of the file. Tiny — a hundred tokens or so per skill, where a token is roughly three-quarters of a word.
• Loaded when relevant: the full instructions. Only when Claude decides this skill applies to what you're asking.
• Loaded on demand: any supporting files. Templates, examples, reference notes — fetched only when Claude actually needs them.

The implication: you can have fifty skills installed and they barely cost anything in terms of Claude's attention. Only the skills Claude actually uses cost real attention.

Compare that to what most people do today — paste a long system prompt at the start of every Claude session. That long prompt sits in Claude's attention for the entire conversation, whether the work needs it or not. Skills push the math the other way: store everything, load only what's needed.

This is why "Skills are just saved prompts" is wrong. They're saved instructions that don't cost you attention until they're actually being used.

Where Skills live

Skills are folders on your computer. You decide who else gets access by where you put them.

| Where the folder lives | Who sees it | Best for | |---|---|---| | Inside a project folder | Just that project | Team workflows shared via git | | In your personal Claude folder | You, across all projects | Your own reusable workflows | | Inside a Claude plugin | Anyone who installs the plugin | Public sharing | | Set by your IT admin | Your whole company | Enterprise rollout |

If two skills with the same name exist in different places, the company-wide one wins, then the personal one, then the project one, then the plugin one. You almost never need to think about this — most builders only ever use one or two of these locations.

The most common pattern is the project-level skill. You drop a .claude/skills/ folder into your project, commit it to git, and now everyone on your team gets the same skills the next time they pull the latest code.

How Claude decides to use a Skill

This is the part that trips up almost everyone.

Claude isn't doing fancy AI matching here. It just reads the label at the top of every installed skill — the description and when_to_use lines — and decides which one fits your request. If the label is vague, Claude won't know when to use it. If the label is specific, Claude will reach for it.

So the most important sentence in your entire skill is the one at the top.

A bad label: "Helps with writing."

A good label: "Edit blog drafts to match the Agent Shortlist brand voice — short sentences, no AI hype words, builder framing."

The good one tells Claude exactly when to reach for the skill. The bad one is so vague Claude has no idea what triggers it. Most skills that "don't seem to work" are actually working fine — Claude just doesn't realise they apply to what you're asking.

We have a separate piece on this coming next in the cluster. The short version: write the label like you're explaining the workflow to a colleague who's never seen your project. Be specific. Use the words your team would actually type when asking for that work.

Skills don't follow you between Claude surfaces

Here's the gotcha that surprised us most.

There are three places you might use Claude: the website at claude.ai, the developer tool Claude Code, and the Claude API (which powers any custom app you build). Anthropic ships Skills in all three places using the same format.

You'd assume — reasonably — that a skill you save in one place is available in the others. It isn't.

| Where you use Claude | How you save a skill there | |---|---| | Claude.ai (website) | Upload a zipped folder via Settings → Features | | Claude Code (developer tool) | Drop the folder into your project on disk | | Claude API (your own app) | Send it via an API call |

A skill saved to Claude.ai doesn't show up in Claude Code. A skill in Claude Code doesn't show up in the API. The format is the same — the file structure, the labels, the instructions all work across surfaces. But you have to manually save the skill into each place where you want to use it.

If you want the same skill in all three places, you save it in all three places.

This is documented but not loudly. Most builders find out the hard way.

Skills vs everything else that looks like Skills

If you've spent any time in Claude Code, you've seen overlapping terms: Skills, MCP servers, subagents, slash commands, CLAUDE.md. They sound similar. Here's the quick cheat sheet.

Skills are reusable workflows. Triggered when Claude decides they apply, or when you call them by name with /skill-name. Use them for tasks you repeat — playbooks, brand voice rules, deploy checklists.

Slash commands are the old version of Skills. Anthropic effectively replaced them. If you see docs about creating custom slash commands, that's old guidance. New work goes in Skills.

Subagents are mini-Claudes that go off and do a task in their own private workspace, then come back with the result. Useful when the work is messy and verbose but the answer is short — like "explore the codebase and tell me which files handle authentication." Skills run alongside your main conversation; subagents run separately.

MCP servers are connections to other software — Slack, Linear, GitHub, your database. They give Claude the ability to do things in those systems. Skills give Claude instructions for how to think. The two work together: a skill might say "when the user asks for sprint status, use Linear to fetch open issues and summarise." The skill is the playbook. The MCP server is what lets Claude actually reach Linear.

CLAUDE.md is the cheat sheet for your specific project. It loads at the start of every conversation and stays in Claude's attention the whole time. Put facts in here that Claude needs to know constantly — your codebase conventions, things to avoid, who your customers are. Don't put things in here that Claude only needs sometimes; that's what Skills are for.

A simplified rule of thumb:

• Information Claude needs every single conversation → CLAUDE.md
• A workflow you repeat → Skill
• A connection to another system → MCP server
• A messy task whose output you don't want cluttering things → Subagent

Most builders only need three of these four (CLAUDE.md, Skills, and sometimes MCP servers). Subagents are an advanced pattern; you can ignore them until you feel the need.

We go deeper on this in the next piece in the cluster: Skills vs MCP servers vs subagents — the architectural map.

What you should actually build first

If you're convinced Skills are worth trying, start here.

Build one skill that captures something you keep retyping. Look at your last twenty Claude conversations. Find the thing you've explained more than twice. The brand voice rules. The way you want code reviewed. The structure of your weekly status update. That's your first skill.

Don't try to be clever. A skill that says "When the user asks for a meeting recap, follow this template" is more useful than something architecturally elaborate. Plain instructions, a specific label, a simple body of text. Ship it. Iterate.

Test the label by deleting the body. If you can't tell what the skill does from just the label at the top, Claude can't either. Rewrite the label until it alone tells the story.

If it's a team workflow, save it in the project folder and commit it to git. The whole point is that everyone on the team gets it on their next pull.

Don't try to build twenty skills before you have one that works. The temptation is to architect a skill library. Resist it. Most skills get refined into usefulness through use, not designed into it on a whiteboard.

The shift in how you work with Claude

Skills aren't really a feature you bolt onto your Claude habit. They're a different way of thinking about it.

Before Skills, every conversation starts from scratch. You re-explain the same context. You paste the same system prompt. You give Claude the same warnings and rules across dozens of sessions. The friction tax is hidden but real.

With Skills, the workflows that used to live in your head or in a Notes app now live alongside your project. Claude reaches for them automatically when the task fits. Your conversations stay focused. Your team inherits your hard-won workflows the next time they pull the latest project.

This is the shift worth making. Stop thinking of Claude as a chat box you give instructions to one prompt at a time. Start thinking of it as something that can load instructions from your project when they're needed.

The first skill you ship will feel small. The fiftieth will feel like infrastructure.