Claude Skills: The Complete Guide to How They Work and How to Use Them

Open a fresh chat with Claude and watch what you do. You tell it your brand voice. You paste the format you want. You list the rules it always forgets. Then you do the actual task. The next morning you open another chat and do the whole warm-up again.

That warm-up is a tax. You pay it every conversation, every task, every time a teammate starts from their own blank window. The AI is not getting smarter about your business. It is starting from zero and you are the one carrying the memory.

A skill is how you stop paying the tax. You write the instructions down once, in a way Claude can load on its own, and the warm-up disappears. To understand why that works, you have to see what a skill actually is, because it is not what most people assume.

Here is the part that trips people up. A skill is not a sentence you paste into a box. A skill is a small folder that lives on disk. At its center is one file named SKILL.md, and that file holds plain-English instructions for one specific job.

Anthropic describes skills as reusable, filesystem-based resources that give Claude domain-specific expertise, the workflows and context that turn a general assistant into a specialist. The word that matters is folder. A prompt is something you say in the moment. A skill is a packaged capability that sits there, ready, and waits to be useful.

That folder can hold more than the one file. It can carry extra documents, examples, even scripts. But the simplest useful skill is a single SKILL.md, and you can write one in a few minutes.

Open a SKILL.md and you find two parts. Up top is a short block of metadata: a name and a description. Below that is the body: your instructions, your examples, the things to never do.

The description is not a label you write and forget. It is the trigger. Claude reads the description of every skill you have and uses it to decide when to switch that skill on. A vague description ("helps with content") means the skill never fires when you need it. A specific one ("Use whenever I share a customer call transcript and ask for a case study") means it fires at exactly the right moment and stays out of the way the rest of the time.

It helps to know how that choice actually happens. Claude is not keyword-matching or running a search. It reads the description and reasons about whether the skill fits what you are doing right now. That is why the exact wording carries so much weight. You are writing for a reader who decides, not a filter that matches.

The limits are generous. The name can run up to 64 characters, lowercase letters, numbers, and hyphens. The description can run up to 1,024 characters, which is plenty of room to spell out both what the skill does and when to use it. Here is a complete, working skill a marketer could write today:

---
name: case-study-writer
description: Write customer case studies from a call transcript in our format. Use whenever I share a customer call or interview and ask for a case study.
---

# Case Study Writer

When I give you a transcript, write a case study with these sections:
1. The problem, in the customer's own words
2. What they tried before us
3. The result, with one hard number if they gave one

Keep it under 400 words. Use their phrasing, not ours.

That is the whole thing. A name, a description that says when to use it, and instructions a smart new hire could follow.

The name and description are the entire standard. Every skill needs them and nothing else. But when a skill runs inside Claude Code, the frontmatter can carry a few more fields that change how and when the skill fires. You will not reach for most of them on day one, and that is fine. They are there for when a skill grows up and needs to be precise.

• allowed-tools and disallowed-tools. Pre-approve or block specific tools while the skill is active, so a skill that should only read files cannot quietly start running shell commands.
• disable-model-invocation. Turn off automatic triggering so the skill runs only when you call it by name. Good for a skill with side effects you do not want fired on a guess.
• user-invocable. Hide a skill from manual use so only Claude reaches for it, or do the reverse.
• context: fork. Run the skill in its own isolated sub-agent context instead of the main conversation, so a big, messy job does not crowd everything else out.
• paths. Limit the skill to certain files or folders, so it only wakes up when you are working in the part of the codebase it knows about.
• model and effort. Override which model runs the skill, or how hard it thinks, for that one task.

None of this exists to make skills complicated. It exists so a skill can be safe and exact inside a real workflow: scoped to the right files, allowed only the right tools, and fired only when you mean it.

Now the part that makes skills more than a tidy place to keep prompts. Quick question before the answer: when a skill is sitting in your setup and you are working on something unrelated, how much of it do you think Claude is reading?

Almost none of it. Skills load in three levels, and Claude only pulls what it needs.

Level one, always on. Claude sees just the name and description of every skill, about a hundred tokens each. Enough to know the skill exists and what it is for. Nothing more.

Level two, on trigger. When the description matches what you are doing, Claude reads the full SKILL.md body, usually a few thousand tokens. The detailed instructions load only at the moment they are relevant.

Level three, as needed. If the skill bundles extra files or scripts, Claude opens those only when the task actually reaches for them. They can be enormous and still cost nothing until that moment.

This is called progressive disclosure, and it is the reason a skill can be long, detailed, and packed with examples while costing almost nothing until the second it is used. Put real numbers on it. A skill that is just sitting there costs about a hundred tokens. The alternative, loading everything up front, is expensive: a stack of tool definitions eagerly loaded into every single message can run tens of thousands of tokens before you have asked for anything. One analysis clocked a typical setup at roughly 32,000 tokens per message, about $160 a month in pure overhead. A skill pays almost none of that until it is actually used.

A giant prompt sits in your context window the whole time, crowding everything else. A skill waits in the wings and walks on only for its scene. That is a difference a prompt can never close.

Instructions are the floor, not the ceiling. Because a skill is a folder, it can also hold reference documents and runnable scripts written in Python or bash.

When the instructions tell Claude to run a script, Claude runs it. The script's code never enters the conversation. Only its output comes back. That is more reliable than asking the AI to rewrite the same logic from scratch every time, and it keeps your context clean, since the work happens in the script instead of in the chat.

Anthropic ships prebuilt skills that work exactly this way for the file types everyone wrestles with: PowerPoint, Excel, Word, and PDF. Ask Claude to build a deck or fill a spreadsheet and a skill quietly does the heavy lifting behind the scenes.

Here is the part that makes skills worth learning once. You build a skill a single time and it works almost everywhere Claude does. The behavior is the same across surfaces. What changes is how you install it, who can see it, and whether an admin can manage it for the whole team. Here is each surface in plain terms.

The Claude apps (web and desktop). The prebuilt skills already work behind the scenes, so when you ask Claude to make a slide deck or a spreadsheet, a skill is doing the work. You can also upload your own skill as a zip file in Settings. Custom skills here are tied to your individual account on the paid plans (Pro, Max, Team, and Enterprise). They are not shared across your whole org automatically, and each teammate uploads their own.

Claude Code. This is the most flexible home for skills. They live on the filesystem as folders, you can keep them for one project or available everywhere, edits take effect in the same session, and the frontmatter carries the extra controls covered above. This is where most people build and refine skills, because you just open the folder and change the file.

The Claude Developer Platform (the API). Teams building their own software upload custom skills through the Skills API and call them by id, and the prebuilt skills (PowerPoint, Excel, Word, and PDF) are available the same way. Skills on the API run inside the code-execution tool. In practice you reference a skill by its skill_id in the request's container, turn code execution on, and pass the three current beta headers (code-execution-2025-08-25, skills-2025-10-02, and files-api-2025-04-14). A custom skill uploaded here is shared across everyone in the workspace.

Claude on AWS and Microsoft Foundry. If your company runs Claude through Amazon Bedrock or Microsoft Foundry, skills behave the same way they do on the API. Same model, same skills, inside the cloud you already use.

The short version is in the table.

One thing the table does not capture: what a skill can actually do differs by surface, and it matters. On the API, skills run with no network access and only the packages already installed in the sandbox. In Claude Code they have full network access and can install what they need. On the Claude apps it depends on your admin's settings. So a skill that fetches a live URL works in Claude Code but not on the raw API.

And one gotcha worth saying out loud: custom skills do not automatically sync across surfaces. A skill you upload to the Claude app is not magically on the API too. The format travels everywhere; the installed copy does not. You put the same folder wherever you want it.

Skills get confused with four other things. Here is the clean line between each, because knowing the difference tells you which one to reach for.

A prompt is a one-off instruction you type and pay for in context every time. A skill is the same instruction saved once and loaded only when its description matches. If you are pasting the same thing more than twice, it wants to be a skill.

MCP is not a competitor, it is a partner. MCP connects Claude to your live tools and data: your CRM, your files, your database. A skill is the know-how for doing a job well. The skill is the recipe, MCP is the pantry, and a good skill can tell Claude to use an MCP tool as one of its steps.

A Project or a custom GPT attaches instructions and files to one workspace or one chat. A skill is portable. It works across the Claude apps, Claude Code, and the API, it loads on demand instead of always sitting in context, and on a team it can be shared and managed centrally.

A subagent is a separate worker with its own job and its own context window. Skills and subagents stack: a skill can run in its own forked context, and a subagent can have skills loaded into it. One is the worker, the other is the playbook the worker follows.

The shape of a skill is the same everywhere: a folder, a SKILL.md with a sharp description, and any files or scripts the job needs. How you install it depends on where you want it to run.

In Claude Code, make a folder and drop a SKILL.md inside it. Put it in your personal skills directory to use it everywhere, in a project's skills folder to share it with that repo, or in a plugin to hand it to other people. It is live in the same session, no restart. If you would rather not start from a blank file, there is a built-in skill whose only job is to help you write skills.

Plugins are also how skills travel at scale. A plugin can bundle several skills, and teams share them through plugin marketplaces, which are really just git repositories that work like an app store. Anthropic keeps a growing public library of ready-made skills at github.com/anthropics/skills, which is also the best place to see how good skills are written.

In the Claude apps, zip the skill folder and upload it in Settings. It is then available to you on the paid plans.

On the API, upload the folder through the Skills API and call the skill by id, with the code-execution tool turned on. This is how a product team ships one skill to its whole workspace at once.

Wherever you install it, the question of whether to build a skill at all is the same. Build one when you keep pasting the same instructions, when a task has a repeatable recipe you care about getting right, or when you want one person's best work available to the whole team instead of trapped in their head. Skip it for a true one-off, or for context that changes every single day. Those belong in a normal prompt or your project notes.

Start with the thing you redo most and are most particular about. Your best-performing email format. Your case-study structure. Your brand voice. Write the recipe down once, and let Claude follow it every time after that.

A skill that never triggers is just a file. A skill that triggers at the wrong time is worse than that. A few habits make the difference.

Write the description for the trigger, not for you. Say what the skill does and exactly when to use it, in the words you would actually use when you need it. "Use when I share a customer call transcript and ask for a case study" beats "case study helper."

Keep one skill to one job. A skill that tries to do five things triggers on all five and does none of them well. Split it.

Lean on progressive disclosure. Keep the SKILL.md body tight and push the long reference material and examples into separate files the skill loads only when it needs them. Your skill can be deep without being heavy.

Use scripts for anything mechanical. If a step has one correct way to run, put it in a script the skill calls. Claude runs it the same way every time and the code never clogs the conversation.

Then test it and tighten. Use the skill on real work, watch where it misfires or misses, and edit. A skill earns its description over a few rounds, not on the first try.

When a skill misbehaves, it is almost always the description. If it will not fire, the description does not match the words you actually use, so add those exact phrases. If it fires when you do not want it, the description is too broad, so narrow it or split the skill in two. If it fires but does the wrong thing, your instructions need a counterexample. And for a skill with real side effects, turn off automatic triggering so it only runs when you call it by name.

The fastest way to get the idea is to see real ones. Here are skills people actually run, the kind you can copy today and adapt in an afternoon.

• case-study-writer. Turns a customer call transcript into a finished case study in your format. Shows how a sharp description ("use when I share a transcript and ask for a case study") makes a skill fire at the right moment.
• changelog-to-newsletter. Turns a product changelog into a customer-ready email in your voice. A repeatable format you would otherwise rebuild every release.
• demo-notes-to-follow-up. Turns rough notes from a sales demo into a follow-up email with the right next step. A marketing and sales workhorse.
• brand-voice. Rewrites any draft in your company's voice, with your rules and your do-not-say list bundled as reference files. The team-wide version of "make it sound like us."
• commit-message-writer. Writes a clean git commit message from your staged changes. A favorite first skill for anyone working in Claude Code.
• The prebuilt document skills. Anthropic's own pptx, xlsx, docx, and pdf skills, which already run behind the scenes when you ask Claude to build a deck or fill a spreadsheet.
• mcp-builder. Anthropic's skill that helps you build an MCP server, a good example of a skill that bundles real reference material.

Two libraries are worth bookmarking: github.com/anthropics/skills (Anthropic's official set) and the community-maintained awesome-claude-skills list. Read a few before you write your own. Good skills teach you the format faster than any guide can.

A skill is powerful for the same reason it deserves a moment of caution: it can run code and read files. A well-made skill does exactly its job. A malicious one, installed carelessly, could read data it should not or misuse a tool you handed it. The fix is simple and familiar.

Treat installing a skill like installing software. Only add skills from a source you trust: ones you wrote, ones from Anthropic, or ones from a team or repo you know. Before you install someone else's skill, open it and read the SKILL.md and any bundled scripts, the same way you would skim a script before running it. Be extra careful with a skill that fetches live URLs or reaches outside your machine, because that is where data can leave. None of this is a reason to avoid skills. It is the same hygiene you already use for browser extensions and npm packages, applied to a folder of instructions.

Anthropic introduced Agent Skills in October 2025 as a way to package real expertise, instructions plus scripts plus resources, into something Claude could pick up and use on its own. In December 2025 they made the format an open standard, published at agentskills.io, so a skill is not locked to one product.

That matters more than it sounds, and it is no longer hypothetical. The SKILL.md format has already been adopted by more than forty shipping agents from across the industry, including OpenAI's Codex, Google's Gemini CLI, GitHub Copilot in VS Code, Cursor, Mistral, Snowflake, Databricks, and JetBrains. One folder, written once, runs in all of them. So when you write a skill you are not betting your team's playbooks on a single vendor's feature. You are writing them in a format built to outlast any one tool, developed in the open and free for anyone to adopt.