What is a Claude skill? A folder of instructions Claude reads only when it needs them
A skill is a folder with a SKILL.md file where you write a repeatable instruction once. Claude keeps only its name and description in view and reads the rest when a task matches.
Part of the guideClaude Code, the complete guide. From installation to your own skills and plugins
In this article
In short
A Claude skill is a folder with a SKILL.md file where you write the instructions for a repeatable task once. Claude always sees only the skill's name and description and reads the full text when a task matches. Skills work in the Claude apps, in Claude Code and through the API, but each of these places keeps its own list.
Someone in the office pastes the same paragraph into Claude for the third time this week. What a quote should look like, which colours, what tone, what never to promise. That is exactly what a Claude skill is for. You save the instruction once in a file, and Claude picks it up on its own when you ask for a quote.
We checked everything below in the Agent Skills documentation, the Claude Code skills docs and the Claude Help Center, as of 10 November 2026. This article is part of a series collected in our Claude Code guide.
What a Claude skill is
A skill is an ordinary folder. It must contain a SKILL.md file, and next to it there can be other files, such as a document template, a longer procedure or a script. Anthropic describes skills as folders of instructions, scripts and resources that Claude loads when they are needed.
SKILL.md has two parts. At the top, between two lines of three dashes, is a short header with a name and a description. Below it is plain Markdown with the instructions. The simplest skill looks like this.
---
name: client-quote
description: Writes a sales quote in the company format. Use when someone asks for a quote, a price to send to a client or a reply to a client enquiry.
---
Write the quote in plain English.
Start with one sentence about the client's problem.
Do not give dates that are not in the notes.
End with the contact details from contact.md.The description field matters most. Anthropic says Claude uses it to decide whether to reach for the skill at all, so it has to say what the skill does and when to use it. The format is an open standard called Agent Skills, described at agentskills.io, so other tools that adopted the standard can read the same folder.
How Claude loads skills in stages
Anthropic calls this progressive disclosure. Claude reads a skill in three steps, and each step takes a different amount of room in the context window.
| Stage | When | Cost |
|---|---|---|
| Name and description | Always, from the start | About 100 tokens per skill |
| SKILL.md body | When a task matches the description | Usually under 5 thousand tokens |
| Extra files and scripts | Only when needed | Nothing until used |
This is why you can keep many skills without stuffing every conversation with them. A script in a skill is even cheaper. Claude runs it and only the output enters the conversation, not the code.
Claude Code works the same way. Its docs point out the difference from CLAUDE.md. Claude reads that file in full at the start of every session, but reads a skill's body only when the skill is used. So a long procedure belongs in a skill, and CLAUDE.md should keep short facts about the project. We cover that file in CLAUDE.md explained.
Skill, project, custom instructions or MCP
These four get mixed up because each one teaches Claude something about your work.
| Tool | What it gives | When it applies |
|---|---|---|
| Custom instructions | General rules for every chat | Always |
| Claude project | Fixed knowledge in project files | In that project's chats |
| Skill | A procedure for one kind of task | When the task matches |
| MCP server | Access to an outside tool | When Claude calls it |
Skills and MCP work well together. Anthropic puts it this way. MCP gives Claude access to tools, and a skill teaches it how to use them well. We write about connecting tools in connecting AI to your calendar.
Where Claude skills work
In the Claude apps, meaning the browser, the desktop app and Cowork, skills live under Customize, in the Skills section. They need code execution and file creation turned on. Anthropic ships its own skills for Word, Excel, PowerPoint and PDF files, and Claude uses them on its own when you ask for such a document. You upload your own skill as a ZIP file.
In Claude Code a skill is a folder on disk. Personal skills go in ~/.claude/skills/ and project skills in .claude/skills/ inside the repository. You can also run a skill by hand with a slash and its name. Old custom commands in .claude/commands/ still work, and the docs now treat them as the older form of skills. Details are in our article on slash commands.
Through the API, skills run together with the code execution tool. Anthropic's ready skills are called there by the IDs pptx, xlsx, docx and pdf, and your own are uploaded through separate endpoints.
One thing surprises many people. According to the Agent Skills docs, custom skills do not move between these places on their own. A skill uploaded in the app has to be uploaded to the API separately, and a folder from Claude Code will not show up in the app. The Claude Code docs describe one exception. When you sign in to Claude Code with the same Claude account, skills enabled on that account download to the terminal, from version 2.1.273. It does not work the other way.
A skill can run code, so check where it came from
A skill is an instruction, but it can also hold scripts that Claude will run. Anthropic recommends using only skills you wrote yourself or got from Anthropic, and reviewing any other skill before you turn it on. Look especially at the scripts and at anything that connects to addresses on the internet.
How to add a ready skill is covered in installing Claude skills. How to write your own, step by step, is in how to write a Claude skill. When you have several skills and want to give them to the whole team, a Claude Code plugin helps.
A good first candidate for a skill is an instruction you already paste into the chat more than once a week. If you want to see which tasks like that in your company AI could take over, our free AI audit looks at where AI can take work off your team.
Documentation for this topic
What would you like to change in your business?
Leave your number. We will talk about your process and see whether we can help. The first call is free.
The service this text is about
Automation and AI / OCRAutomation of document re-typing, OCR and checking rules, and your data stays with you.