What Are Claude Skills? How They Work and How to Make One

What are Claude skills? They're folders of instructions, and optionally scripts and files, that Claude loads when a task needs them.

Each skill has a SKILL.md file with a short name and description at the top. Claude reads only those descriptions until a request matches, then loads the full instructions. Anthropic describes them as "folders that include instructions, scripts, and resources that Claude can load when needed."

As of October 2026, skills work on every Claude plan, including Free, in the Claude apps, Claude Code and the API. Anthropic launched them on October 16, 2025 and published the format as an open standard in December 2025. Codex, Cursor, GitHub Copilot and Gemini CLI now read the same format.

How we researched this: Anthropic's skills docs for Claude Code, its Agent Skills platform docs and help center, plus the agentskills.io specification. We also read the skills docs of Codex, Cursor, Copilot and Gemini CLI. All checked October 30, 2026.

What are Claude skills, in plain terms?

A skill is a reusable how-to. Instead of pasting the same instructions into every chat ("format reports like this", "check these five things before a release"), you write them once in a skill. Claude picks it up whenever it's relevant, or you call it by name, like /release-check in Claude Code.

Anthropic's own one-liner is the clearest. "Skills teach Claude how to do something."

A skill can be pure text, or it can bundle scripts Claude runs, templates it fills in, and reference files it reads only when needed.

How do Claude skills work?

Skills use what Anthropic calls progressive disclosure. Claude loads a skill in three stages, so having many installed doesn't fill up its memory:

The numbers come from Anthropic's platform docs. They add up to a practical point: 20 installed skills cost Claude roughly 2,000 tokens of standing context, about the length of a short article. That's why the description matters so much. It's the only part Claude sees when deciding whether to use the skill.

What's inside a skill?

A skill is a folder named after the skill, with one required file:

release-check/
├── SKILL.md        (required: frontmatter plus instructions)
├── scripts/        (optional: code Claude can run)
├── references/     (optional: docs Claude reads when needed)
└── assets/         (optional: templates, images, data)

The top of SKILL.md is YAML frontmatter. Per the open specification:

• name: up to 64 characters, lowercase letters, numbers and hyphens only, matching the folder name. Anthropic's docs add that it can't contain the words "anthropic" or "claude".
• description: up to 1,024 characters. It should say what the skill does and when to use it.

Keep the main file under 500 lines and move long reference material into separate files. Claude Code also supports extra fields, such as allowed-tools to limit what a skill can do and context: fork to run it in a separate subagent. Those Claude Code fields cause an error if you upload the same skill to claude.ai, so keep shared skills to the standard fields.

Skills vs MCP, CLAUDE.md, slash commands and subagents

These overlap, and picking the wrong one wastes context. Here's how they divide up, based on Anthropic's skills explainer and the Claude Code docs:

Anthropic sums up the most common confusion in one line. "MCP connects Claude to data; Skills teach Claude what to do with that data."

The Claude Code docs also give a good rule for CLAUDE.md. Unlike CLAUDE.md, "a skill's body loads only when it's used". So if a section of your CLAUDE.md has grown into a step-by-step procedure, move it into a skill.

If MCP is new to you, our guide to what an MCP server is explains it.

How to make your first Claude skill

In Claude Code

1. Create a folder: .claude/skills/diff-summary/ for one project, or ~/.claude/skills/diff-summary/ for all of them.
2. Add a SKILL.md file inside it.
3. Write the frontmatter and instructions.

Here's the example from Anthropic's Claude Code docs. The !`git diff HEAD` line runs the command and inserts its output before Claude reads the skill:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

Claude will now use it when you ask "what changed?", or you can run /diff-summary directly. In Claude Code every frontmatter field is optional; the name defaults to the folder name.

In the Claude apps

1. Turn on code execution in Settings under Capabilities. Skills need it.
2. Put your skill folder in a ZIP file, with the folder itself at the root of the ZIP.
3. Go to Customize, then Skills, then the + button, and choose Upload a skill.
4. Test it with a few different prompts, and rewrite the description if Claude doesn't pick it up.

On Team and Enterprise plans, an owner has to enable skills for the organization first. The most common upload errors, per Anthropic's help center, are a folder name that doesn't match the skill name, invalid characters, or a missing SKILL.md.

Let Claude write it

Anthropic's official skill-creator skill does this for you. It drafts the skill, writes test prompts, runs them, and helps you improve the result. It's in Anthropic's skills repository, along with the document, design and testing skills covered in our roundup of the best Claude skills.

Tips for skills that actually trigger

• Write the description for the model, not for people. Say when to use it, using the words people actually type: "Use when the user asks for a release checklist or says they're about to ship."
• One job per skill. A skill that does five things has a vague description and triggers at the wrong times.
• Put the steps in order. Skills work best as a procedure, not a pile of tips.
• Move big reference material into references/, so Claude loads it only when a step needs it.
• Use scripts for anything that must be exact, like validation or file conversion. Only the script's output enters the context.

Do Claude skills work in other tools?

Yes. The format is now an open standard, and several other coding agents read it:

Paths come from each tool's docs: Codex, Cursor, Copilot and Gemini CLI. If your team uses more than one agent, .agents/skills/ is the most widely read location. Stick to the standard frontmatter fields so the same skill works everywhere.

Custom skills don't sync between Claude surfaces, though. Skills you upload on claude.ai are per user, API skills are per workspace, and Claude Code skills live in your files.

Are Claude skills safe?

Your own are. Other people's need checking, because a skill can include scripts that run on your machine and instructions Claude will follow. Anthropic's docs say to use skills only from trusted sources: "those you created yourself or obtained from Anthropic". They also warn that a malicious skill could lead to "data exfiltration, unauthorized system access, or other security risks."

Before installing a third-party skill:

1. Read SKILL.md and every script in the folder.
2. Look for network calls, and for instructions to fetch files from a URL at runtime. A skill that loads its instructions from the web can change after you've checked it.
3. Check what files it reads and writes.
4. In Claude Code, use allowed-tools to limit what it can do.

Our guide to Claude Code's permission modes covers how to keep an agent from running commands you didn't approve.

FAQ

Are Claude skills free?

Yes. Skills are available on every Claude plan, including Free, as long as code execution is turned on. Using them still counts toward your plan's usage limits.

What's the difference between Claude skills and Claude Code skills?

They're the same format. Claude Code reads skills from folders on your computer and supports a few extra settings; the Claude apps use skills you upload as ZIP files. Anthropic's document skills for Word, Excel, PowerPoint and PDF are built into the apps and the API, not Claude Code.

Where are Claude skills stored?

In Claude Code, in ~/.claude/skills/ for personal skills or .claude/skills/ inside a project. On claude.ai, they're stored in your account after you upload them.

Can Claude create skills for me?

Yes. Ask Claude to use Anthropic's skill-creator skill, describe the task, and it will draft the SKILL.md, write test prompts and help you refine it.