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
  1. What a Claude skill is
  2. How Claude loads skills in stages
  3. Skill, project, custom instructions or MCP
  4. Where Claude skills work
  5. A skill can run code, so check where it came from

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.

SKILL.md
---
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.

StageWhenCost
Name and descriptionAlways, from the startAbout 100 tokens per skill
SKILL.md bodyWhen a task matches the descriptionUsually under 5 thousand tokens
Extra files and scriptsOnly when neededNothing 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.

ToolWhat it givesWhen it applies
Custom instructionsGeneral rules for every chatAlways
Claude projectFixed knowledge in project filesIn that project's chats
SkillA procedure for one kind of taskWhen the task matches
MCP serverAccess to an outside toolWhen 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.

When is the best time to call?
Controller: Oleksandr Bondarenko (BondSoft)Privacy PolicyTerms of Service
Legal details

The data controller is Oleksandr Bondarenko, trading as Oleksandr Bondarenko Software Solutions (BondSoft), ul. Jana Heweliusza 11, 80-890 Gdańsk, Poland, NIP 5833576264, e-mail: office@bondsoft.pl.

We process your data solely to contact you about your enquiry and to present an offer — on the basis of your consent (Art. 6(1)(a) GDPR and Art. 398 of the Polish Electronic Communications Law) and our legitimate interest in handling the enquiry (Art. 6(1)(f) GDPR).

Providing the data is voluntary but necessary for us to reply. You may withdraw your consent at any time by writing to office@bondsoft.pl — this does not affect the lawfulness of processing before the withdrawal.

You have the right to access your data, rectify it, erase it, restrict its processing, transfer it, and lodge a complaint with the President of the Polish Personal Data Protection Office.

Full information: Privacy Policy.

Send us an email

The service this text is about

Automation and AI / OCR

Automation of document re-typing, OCR and checking rules, and your data stays with you.