Claude Skills, the Complete Guide: What They Are and How I Run 56

A Claude skill is a folder with a file called SKILL.md in it. The file holds instructions for one kind of job, and Claude reads it only when your request matches that job. You write the steps once and stop pasting them into every chat. Skills work in Claude Code, claude.ai and the API, and they follow an open standard.

I'm not a developer, and my workspace has 56 skills in it as of 28 October. Forty of them I built, and 16 are other people's, such as Anthropic's frontend-design. I didn't write a single SKILL.md by hand. This guide covers what a skill is, how it works, where to find good ones, how to install one when it won't show up, how to make your own, and where skills stop being the right tool.

What is a Claude skill?

Anthropic's own definition is reusable, filesystem-based resources that give Claude domain-specific expertise. The Claude Code docs put it more plainly: you create a SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses the skill when it's relevant, or you can call one directly by typing /skill-name.

The short version I use: a prompt is a sentence you say once, and a skill is the same instruction saved in a folder so it's there every time. Anthropic's docs draw the same line. Prompts are conversation-level instructions for one-off tasks, while skills load on demand. In business terms, a skill is an SOP.

The names "Claude skills", "Anthropic skills" and "agent skills" all point at SKILL.md folders. Anthropic published them as an open standard on 18 December 2025, per an update on its engineering post, with the spec at agentskills.io. The Claude Code docs say its skills follow that standard, which works across multiple AI tools.

How does a skill actually work?

A skill is loaded in three layers, and that's the whole trick. Anthropic calls it progressive disclosure, and its engineering post names it the core design principle that makes skills flexible and scalable.

Checked 28 October 2026 against the Agent Skills overview.

That's why a skill beats a long pasted prompt: the Claude Code docs say a skill's body loads only when it's used, so long reference material costs almost nothing until you need it.

The part to get right is the description. It's the only text Claude sees before deciding whether to open the skill. Anthropic requires it to say both what the skill does and when to use it, and caps it at 1,024 characters in the spec. Claude Code's skill listing cuts the combined description at 1,536 characters, so put the key use case first.

Mine follow one pattern: what the skill does, the phrases a person would say to trigger it, and a "Do NOT use for" line naming the neighbours it must stay out of. That last line matters once you have more than a few skills, because two with overlapping descriptions fight over the same request.

Where do Claude skills work, and are they free?

Skills work in Claude Code, claude.ai and the Claude API, per Anthropic's overview page. They don't travel between them. The same page says custom skills don't sync across surfaces, so a skill you upload to claude.ai isn't automatically in Claude Code, and the other way round.

On plans, Anthropic's two pages disagree slightly. The platform docs say uploading custom skills is available on Pro, Max, Team and Enterprise with code execution on. The help center currently lists Free as well. If you're on Free, check your own settings before assuming either. Skills cost nothing to write or download; the plan gates where you can use them. Checked 28 October 2026.

One more catch: skills in the API have no network access, while Claude Code skills have full network access, so a script that calls a website works in one place and not the other.

Do Claude skills work in Cowork?

Partly, and it depends on who set them up. Anthropic's help article on managing skills says organization-wide skill management is on Team and Enterprise plans. An owner uploads a skill and it appears in chat and in Cowork, where members can switch individual skills off.

The surprise is the folder. The Claude Code docs say a personal skill in ~/.claude/skills/ loads in all your projects on that machine but not in Cowork or cloud sessions. So the skills in this guide, which live on my Mac, wouldn't follow me into Cowork. Cowork itself has its own guide.

Where do I find Claude skills?

Three places, and the words "marketplace" and "library" mean different things in each.

GitHub. The main one is Anthropic's anthropics/skills repository, described as the public repository for Agent Skills. It had 184.4k stars on 28 October. It holds example skills in four groups (creative and design, development and technical, enterprise and communication, and the document skills), plus the spec and a template. Most of it is Apache 2.0, though the Word, PDF, PowerPoint and Excel skills are source-available, not open source. The README says the skills are for demonstration, so test them before relying on them.

Plugin marketplaces inside Claude Code. A plugin is a directory of skills, agents, hooks or MCP servers that installs as one unit, and a marketplace is a catalog of plugins. The plugins docs are careful to say a plugin marketplace isn't the same thing as the Claude Marketplace website. To add Anthropic's catalog and install a set, you run /plugin marketplace add anthropics/skills, then /plugin install example-skills@anthropic-agent-skills. Plugin skills load under a namespace, as /plugin-name:skill-name.

Community repos. Anyone can publish a skill folder on GitHub. That's where most of the interesting ones are, and where the security question starts.

Update, 4 November 2026: how do you install find-skills, and what should you ask it?

find-skills is a free skill from Vercel Labs that finds other skills for you. You say what you're trying to do, it checks the skills.sh leaderboard, searches the whole directory if the leaderboard has nothing, and installs the one you pick. Its page showed 4.2M installs on 4 November 2026, and its repo, vercel-labs/skills, is MIT-licensed with about 38,000 stars. It's one of the skills I keep installed myself.

The install line, which needs Node.js 22.20 or later:

npx skills add vercel-labs/skills --skill find-skills -g -a claude-code

-g installs it for your whole user account instead of one project, and -a claude-code tells the installer which agent it's for, so you only run it once.

After that you ask in plain words, and you don't need to name a skill. These three requests are worth trying first. The middle column is what fit each one in a search of the skills.sh directory on 4 November.

Its instructions tell Claude to check quality before it recommends anything: prefer skills with over 1,000 installs, be careful with anything under 100, favour known sources such as Vercel, Anthropic and Microsoft, and look at the repo's stars. Then it shows you the skill, its install count and the command. Once one is installed, Claude already knows how to do that job the next time you ask.

An install count tells you a skill is popular, and it doesn't tell you it's safe. On the find-skills page, skills.sh lists three audits: Gen Agent Trust Hub and Socket pass it, and Snyk gives it a medium warning, because it reads community-published content that could carry instructions aimed at your agent. So the safety checklist further down still applies to whatever it finds. Its instructions also mention a -y flag that skips the installer's confirmation, so ask Claude to show you the skill before it installs anything. The installer collects anonymous usage data too, per its README, and DISABLE_TELEMETRY=1 turns that off.

What are some good Claude skills, and which ones have I used?

Apart from Anthropic's skill-creator, which comes up below, these four skills made by other people have done real work for me.

• marketingskills and frontend-design. Both have produced real output in my own work, the ad copy and the page look. I wrote up what each one fixes and the install command, along with three more I'd added more recently.
• Claude SEO. I installed it and ran it against scalr.sg, and wrote up the whole audit, command by command.
• Remotion's official skill. Every animation in my reels is made by prompting Claude with it, which I covered in the Remotion skill write-up.

This blog also covers twelve LinkedIn skills, thirteen Instagram skills, an Apple design-rules skill, the Claudex loop and /brag. If you want a starting point from Anthropic itself, its document skills for Word, PDF, Excel and PowerPoint are already built into claude.ai and the API, per the overview page, though not into Claude Code. Anthropic's free certificate courses cover the same ground from the other direction.

How do I install a skill, and why isn't it showing up?

In Claude Code, a skill is just a folder in the right place. The docs list four locations:

If two skills share a name, enterprise wins over personal, and personal wins over project. The folder name, or the name field when you set one, becomes the command you type. Claude Code picks up edits within the current session, so you don't need a restart.

In claude.ai, you upload the skill as a ZIP under Customize or Settings, and the menu name has shifted between Anthropic's own pages, so look for Skills in either. The upload fails if the ZIP is too large, if the folder name doesn't match the skill name, or if SKILL.md is missing.

When a skill isn't showing up or doesn't fire, the docs' troubleshooting list is short and worth following in order:

One cause that only shows up with many skills: Claude Code keeps a character budget for the skill listing, set at 1% of the model's context window. When it overflows, descriptions get dropped starting with the skills you use least, and with them the keywords Claude matches on. /doctor estimates the cost, /skill-doctor helps find skills to turn off, and claude plugin validate finds files whose frontmatter doesn't parse.

How do I create my own Claude skill?

The smallest valid skill is a folder with a SKILL.md that has a name and a description and some instructions underneath. The spec says the name uses lowercase letters, numbers and hyphens, stays at 64 characters or fewer, and matches the folder name. Anthropic also says to keep SKILL.md under 500 lines and push long reference material into separate files that load only when needed.

You can write that file by hand. I don't, which is my rule and not Anthropic's. Anthropic ships a skill called skill-creator, and mine is in my skills folder. Its own instructions have it draft the skill, run test prompts with and without the skill, grade both, and tune the description when the skill fires on the wrong requests. My workspace charter says a skill gets built through skill-creator or not at all. The reason is written there: an old folder of 30-odd skills piled up with no tests and overlapping triggers.

Here's the loop I follow, which is written into my project instructions:

I own the thinking and the judgment, and Claude owns turning it into skill code. That split is how a non-developer ends up building 40 of them. If the steps you want are already in a video, you can turn a YouTube tutorial into a skill instead of dictating them. Anthropic also keeps a skill authoring guide if you want the official reading.

What do real skills look like at different sizes?

Here are four of mine, measured on 28 October. The size is the SKILL.md length and the number of reference files, since long procedures belong in references and not the main file.

The reels-editor skill sits behind a pipeline that has finished 103 reels for my own page, walked through in every stage my AI runs to edit a video. request-approval is the one that keeps a human yes in front of anything that publishes or sends.

A caveat on sharing. Some of my skills carry extra frontmatter fields such as status and written. Claude Code ignores them, but Anthropic's docs say claude.ai uploads and the API allow only six fields (name, description, license, compatibility, metadata, allowed-tools) and treat others as a hard error. I'd have to strip them first.

How many Claude skills should you have?

As many as you have jobs that keep coming back. Is 56 too many or too few? Some people would say too many, some would say too few, and some people keep hundreds. "Skills" has become a word thrown around everywhere, with lists of open-source skills shared all over the internet.

I go back to the SOP idea. If a job in your business needs a set way of doing it, it gets an SOP, and a business with more of those jobs ends up with more skills. That's how mine got to 56.

The catch is cost. Every skill puts its name and description in front of Claude at the start of every session, used that day or not, and Anthropic puts that at about 100 tokens a skill. So the more skills you keep, the more tokens go on reading them before you've asked for anything. More descriptions also compete for the same request, which is how a skill gets read by accident.

That's why I turned off the skills the Claude app came with. It shipped with a set of Anthropic's own skills switched on, some of them were getting read by accident, and I wasn't using any of them. The ready-made ones are tempting to leave on, but I build my own.

My way of building has two parts:

My skill-creator is the example. It started as Anthropic's, and it now carries my own rules on top.

How are skills different from MCP, agents, commands and CLAUDE.md?

They sit at different layers, and most of the confusion comes from treating them as rivals. Anthropic's explainer gives the cleanest split: MCP connects Claude to data, and skills teach Claude what to do with that data.

On commands, the Claude Code docs say a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. On CLAUDE.md, the docs suggest turning a section into a skill once it has grown from a fact into a procedure.

One thing skills can't do is guarantee a rule holds every time. Claude follows a skill with judgment and can skip a step later in a long session. Anthropic's advice for a rule that must hold is to move it into a hook, which runs every time its event fires. Hooks and subagents have their own guide here, so I'll leave them as a row.

Are Claude skills safe to install?

A skill can run scripts and read files, so installing one is closer to installing software than to saving a prompt. Anthropic says so directly: use skills only from trusted sources, meaning ones you wrote yourself or got from Anthropic, audit every bundled file, and treat a skill that fetches content from an external URL as risky.

Read strictly, that rules out most community skills on GitHub, which is the honest tension here. A short checklist, built from Anthropic's guidance and plain caution:

On Enterprise plans, Anthropic's help center says Claude scans third-party skills and plugins users upload and blocks malicious ones.

When are skills the wrong tool?

Skip a skill for a one-off request, since a single prompt is cheaper than a folder. Skip it for a fact that's always true, because that belongs in CLAUDE.md. Skip it when Claude needs live access to something, because that's MCP. And skip it for a rule that can never be broken, because that's a hook.

The other limit is volume. Past a point, more skills makes each one harder to trigger and costs tokens on every session. My own charter says to review any skill that hasn't fired in 90 days. Where skills sit in the bigger picture is in the four levels of AI adoption.

Key takeaways

• A Claude skill is a folder with a SKILL.md file. Claude loads its short description always and its body only when a task matches.
• The description decides everything. State what the skill does, the phrases that should trigger it, and what it must not be used for.
• Find skills in Anthropic's anthropics/skills repository (184.4k stars on 28 October 2026), in plugin marketplaces inside Claude Code, and in community repos you read before installing.
• In Claude Code, put a skill in ~/.claude/skills/ for every project or .claude/skills/ for one repository. Custom skills don't sync between claude.ai, the API and Claude Code.
• Keep a skill for each job that keeps coming back, like an SOP, and no more. Every skill's description is read at the start of every session, so unused ones cost tokens.
• Build your own through skill-creator, and keep MCP, CLAUDE.md, hooks and subagents for the jobs they fit.

FAQ

What are Claude skills?

Claude skills are folders containing a SKILL.md file of instructions, plus optional scripts and reference files, that Claude loads only when your request matches the skill's description. They work in Claude Code, claude.ai and the API, and they follow the open Agent Skills standard Anthropic published on 18 December 2025.

Are Claude skills free?

The skills are free to download and write, and Anthropic's example repository is mostly Apache 2.0. Using custom skills depends on your plan: Anthropic's platform docs say Pro, Max, Team and Enterprise with code execution on, while its help center currently lists Free too. Checked 28 October 2026.

How many Claude skills should I have?

As many as you have repeated jobs that need a set way of doing them. Each skill's name and description load at the start of every session, about 100 tokens a skill per Anthropic, so a skill you never use still costs tokens and can be picked by mistake. Switch off the ones you don't use, including any that came with the app.

Where do I put a Claude skill in Claude Code?

Put it in ~/.claude/skills/<skill-name>/SKILL.md to use it in all your projects, or in .claude/skills/<skill-name>/SKILL.md to use it in one repository. Claude Code picks up edits within the current session, and if two skills share a name, personal wins over project.

How do I install the find-skills skill for Claude?

Run npx skills add vercel-labs/skills --skill find-skills -g -a claude-code, which needs Node.js 22.20 or later. It's a free, MIT-licensed skill from Vercel Labs that had 4.2M installs on skills.sh on 4 November 2026. After that, you describe the job in plain words and it suggests skills to install.

Are Claude skills safe to install from GitHub?

Only after you read them. Anthropic says to use skills only from sources you trust, meaning ones you wrote or got from Anthropic, and to audit every bundled file, because a skill can run scripts and fetch outside content. Plugins can run code with your user privileges, so treat any install like software.

What is the difference between Claude skills and MCP?

MCP connects Claude to outside data and tools, while a skill teaches Claude what to do with them. A skill is a folder of instructions that loads when a task matches, and an MCP server is a connection Claude calls into. Many setups use both: MCP to reach the data, a skill to say how to handle it.