What Claude Skills are and how to create one

What are Claude skills? They are saved instructions that teach Claude a task once, so you can reuse it in every conversation. A skill is a small folder, and Claude opens it only when a request needs it. This chapter explains what goes into a SKILL.md file, how Claude decides to load one, how skills compare with MCP, projects and custom instructions, and how to write your first skill. For the list of skills we cover and install steps for each surface, see the Claude Skills catalog.

What a Claude skill is

Anthropic's help center defines skills as folders of instructions, scripts and resources that Claude loads dynamically to do better at specialized tasks. Typical uses are applying brand guidelines to a document, formatting meeting notes the way your company wants, or running a personal routine the same way each time.

Every skill needs one file, SKILL.md. It starts with YAML front matter holding two required fields:

• name: up to 64 characters, lowercase letters, numbers and hyphens only. It cannot contain the reserved words "anthropic" or "claude", or XML tags.
• description: what the skill does and when Claude should use it. The developer docs allow up to 1,024 characters. The Claude.ai help center gives a 200-character limit for uploaded skills, so keep it short if you plan to upload there.

Below the front matter come the instructions in plain Markdown. A skill can also carry extra files: a reference document, a template, or a script that Claude runs instead of writing the same code from scratch.

Anthropic ships ready-made skills for Word, Excel, PowerPoint and PDF files. Anyone can write a custom skill, and the format is an open standard published at agentskills.io, so the same folder also works in other tools that support it, such as Cursor, Gemini CLI, GitHub Copilot and OpenAI Codex.

How Claude loads a skill

Skills use what Anthropic calls progressive disclosure. Claude loads a skill in stages, so an installed skill costs almost nothing until it is used.

In practice it works like this. Claude sees the line "pdf-processing: extract text and tables from PDF files..." in its system prompt. You ask it to summarize a PDF. Claude matches the request to the description, reads SKILL.md, and follows the instructions. If the skill also has a form-filling guide and your task does not involve forms, that file stays unread.

This is why the description matters more than any other line. Anthropic's docs say the description is what Claude matches your request against, so it must say both what the skill does and when to use it.

Skills vs MCP, projects and custom instructions

Claude has several ways to give it context, and they solve different problems. Anthropic's help center compares them like this, and the Claude Code docs add the rows for CLAUDE.md, commands and subagents.

The short version: MCP gives Claude access to a system, and a skill tells Claude how to do a job. They work together. A skill can describe how to file a support ticket, and an MCP server can be the thing that files it.

Two other comparisons come up in Claude Code. Slash commands: custom commands in .claude/commands/ have been merged into skills, so a skill named deploy and a command file named deploy.md both create /deploy. Skills add supporting files, invocation control and automatic loading. Subagents: a skill normally runs inside your conversation, but setting context: fork in its front matter runs it in a separate subagent that does not see your chat history and returns only its result.

How to create a Claude skill

Here is a minimal skill you can copy. It turns rough meeting notes into a fixed format.

meeting-notes/
  SKILL.md

---
name: meeting-notes
description: Turns rough meeting notes into a summary with decisions, owners and deadlines. Use when the user pastes meeting notes or asks for a meeting summary.
---

# Meeting notes

## Instructions
1. Read the notes the user provides.
2. Write a summary of no more than five bullet points.
3. List every decision under "Decisions".
4. List every task as "Owner: task (deadline)" under "Action items".
   If a task has no owner or deadline, write "unassigned" or "no date".
5. Do not add tasks or decisions that are not in the notes.

## Example
Input: "talked pricing, Ana to send new deck by Fri, agreed to drop tier 3"
Output:
- Summary: pricing review
- Decisions: drop tier 3
- Action items: Ana: send new pricing deck (Friday)

Then install it where you work:

1. Claude Code: save the folder to ~/.claude/skills/meeting-notes/ for all projects, or to .claude/skills/meeting-notes/ in a repository. Claude Code watches these folders, so edits apply in the current session. Call it with /meeting-notes or let Claude pick it up from the description.
2. Claude.ai: zip the folder so that the folder itself is the root of the ZIP, then upload it under Customize > Skills. Code execution must be on. The help center lists skills on Free, Pro, Max, Team and Enterprise plans; the developer docs list custom uploads for Pro, Max, Team and Enterprise, so check your own settings.
3. API: upload the skill through the /v1/skills endpoints. Uploaded skills are shared with everyone in the workspace.

In Claude Code you can control who triggers a skill. disable-model-invocation: true means only you can start it by typing its name. user-invocable: false means only Claude can. allowed-tools pre-approves specific tools while the skill runs.

Write a description that triggers

Most skill problems are description problems. Claude Code's troubleshooting table gives two fixes: if a skill never triggers, add the words users would actually say; if it triggers too often, make the description more specific, or turn off automatic invocation. Anthropic's tutorial on building skills through chat suggests telling Claude three things: the exact format you need, the tone and who reads the result, and one example you were happy with. You can hand that to Claude directly:

Help me turn a task I repeat into a Claude skill.

Task: [what I do, step by step]
Format of the result: [exact structure, headings, length]
Who it is for and how it should read: [audience and tone]
One example I was happy with: [paste the example]

Write the SKILL.md file. The description must say what the skill does and when to use it, in under 200 characters. Keep the instructions short and list anything Claude must not do.

If you want a guided process with test runs, Anthropic publishes a skill for exactly this job: skill-creator.

Test and maintain a skill

Start a new conversation and ask for the task in a few different ways. In Claude.ai, Anthropic's tutorial says to look for "Reading [skill name]" in Claude's thinking to confirm the skill loaded. Keep each skill focused on one workflow, start with plain Markdown before adding scripts, and include an example input and output.

Keep in mind three limits:

• Skills mostly do not sync. The API keeps its own copies. Claude Code signed in with a claude.ai account (version 2.1.273 or later) downloads the skills enabled on that account, but skills you write in Claude Code never upload back.
• Runtimes differ. API skills have no network access and cannot install packages. Claude Code skills have the same network access as any program on your computer. In Claude.ai, network access depends on your settings.
• Skills carry risk. A skill can run code, so Anthropic recommends installing only skills you wrote or got from a source you trust, and reading every file first.

Skills sit inside a bigger topic: deciding what goes into the model's context and when. Our chapter on context engineering covers that, and the system prompts guide covers the always-on instructions that skills complement. If you use Claude Code daily, keep the Claude Code cheat sheet open next to this page.

FAQ

What are Claude skills in simple terms?

They are saved instructions for one task, stored as a folder with a SKILL.md file. Claude keeps a one-line description of each skill in mind and opens the full instructions only when your request matches it.

What is the difference between Claude skills and MCP?

MCP connects Claude to outside services and data. A skill describes a procedure. Anthropic's help center says MCP provides the connections, skills teach how to complete a workflow, and the two can work together.

How do I use a skill in Claude Code?

Put the skill folder in ~/.claude/skills/ or .claude/skills/. Claude uses it when your request matches its description, or you can type /skill-name to run it directly.

Do Claude skills work in other AI tools?

The SKILL.md format is an open standard. Agentskills.io lists tools that support it, including OpenAI Codex, Cursor, Gemini CLI and GitHub Copilot. Check each tool's documentation for where it reads skills from.

Do I need to code to create a skill?

No. A skill can be plain instructions in Markdown. Anthropic's tutorial notes you can create one by describing the task to Claude in a conversation.