Claude Skills: what they are, how to turn them on, and how to write your own

The short answer

Claude Skills are folders of instructions that Claude opens only when a task needs them. Anthropic, the company that makes Claude, also calls them Agent Skills. Each skill is a folder with one file called SKILL.md: a short header with a name and a description, then plain steps for Claude to follow. The folder can also hold scripts, templates and reference files. Claude reads the name and description of every skill at the start, and loads the rest only when your request matches. Skills work in the Claude apps, in Claude Code and in the Claude API. In the app, you turn on code execution, then switch skills on under Customize, then Skills, or upload your own as a ZIP file. In Claude Code, you drop the folder into the skills folder of your home or your project. To make a good one, say what it does and when to use it, keep the steps short, and test it on real requests.

This guide is built only from Anthropic’s own pages, read on 19 October 2026 and linked at the end. Where those pages disagree with each other, we say so and give you the safe choice.

What is a Claude skill?

A skill is a small package of know-how. Anthropic’s Help Center calls skills "folders of instructions, scripts, and resources that Claude loads dynamically." Think of it as the page of notes you would hand a new teammate on day one: how we do this job, step by step, with an example.

Every skill has one required file, SKILL.md. It starts with a header in a format called YAML, between two lines of three dashes. Only two fields are required:

• name: up to 64 characters, only lowercase letters, numbers and hyphens. It cannot contain the words "anthropic" or "claude".
• description: up to 1,024 characters in Anthropic’s developer docs. It must say what the skill does and when to use it.

Under the header come the instructions, written in plain Markdown. Next to SKILL.md you can add more files: a longer reference, a template, or a script Claude runs.

Anthropic introduced skills on 16 October 2025. On 18 December 2025 it published the format as an open standard at agentskills.io, and that site now lists other tools that read the same folders, including Cursor, GitHub Copilot, VS Code, Gemini CLI and OpenAI’s Codex. So a skill you write for Claude is not locked to Claude.

Why skills do not slow Claude down

Skills load in three steps, which Anthropic calls progressive disclosure. That is why you can install many of them.

How a skill loads, in Anthropic's own figures (Agent Skills overview, read 19 October 2026).

Level	When Claude reads it	What it costs	What it holds
1. The header	Always, at the start	About 100 tokens per skill	The name and the description
2. The instructions	When your request matches	Under 5,000 tokens	The body of SKILL.md
3. Extra files	Only when needed	Nothing until read; a script only adds its output	References, templates, scripts

Swipe the table to see every column

The lesson for writers: the description does all the work of getting your skill picked. If it is vague, Claude never opens the rest.

How are skills different from Projects, custom instructions and MCP?

They solve different problems, and they work well together. This is how Anthropic’s Help Center draws the lines.

Skills next to Claude's other ways to remember how you work (Claude Help Center, read 19 October 2026).

Feature	What it does	When it applies
Skills	Steps for doing one kind of task	Only when a task needs it, in any chat
Projects	Fixed background knowledge	Every chat inside that project
Custom instructions	Broad preferences	Every conversation
MCP	A connection to an outside tool or data	Gives Claude access; a skill shows how to use it

Swipe the table to see every column

Where do Claude skills work?

In three places, and each one handles your files differently. Custom skills do not travel freely between them, so it helps to know where yours lives.

Skills on each Claude surface, from Anthropic's docs and Help Center (read 19 October 2026).

	Claude apps	Claude Code	Claude API
How you add your own	Upload a ZIP under Customize, then Skills	Put the folder in a skills folder on your computer	Upload through the Skills API
Anthropic’s Word, Excel, PowerPoint and PDF skills	Built in, used when you make files	Not built in; Anthropic offers them as a plugin	Built in, by name: docx, xlsx, pptx, pdf
Who sees your custom skill	Only you, until you share it	You, or everyone in the repo, or a plugin’s users	Everyone in the workspace
Internet from inside a skill	Full, partial or none, set by you or an admin	Same as any program on your computer	None, and no installing packages
What you need	Code execution turned on	Nothing extra	The code execution tool

Swipe the table to see every column

One more rule about moving skills around. Anthropic’s Help Center says skills you add in the app now sync one way to Claude Code, which needs Claude Code version 2.1.273 or later and a claude.ai sign-in. Skills you upload through the API stay in the API, and a skill folder in Claude Code does not appear in the app.

How do you turn on skills in the Claude app?

1. Turn on code execution

   Skills need it. On Free, Pro and Max, open Settings, then Capabilities, and turn on "Code execution and file creation". On Team and Enterprise, an owner opens Organization settings, then Plugins and skills, then the Policy tab, and turns on both code execution and Skills.

2. Switch on the skills you want

   Open Customize, then Skills. Anthropic’s own skills for Word, Excel, PowerPoint and PDF are listed there. Once they are on, Claude uses them by itself when a request fits. You do not call them by name.

3. Upload your own

   In Customize, then Skills, click the plus button, then Create skill, then Upload a skill, and choose a ZIP file. The ZIP must hold the skill folder itself, not loose files, and the folder name must match the skill name.

A note on plans, because Anthropic’s pages do not agree. The Help Center lists Skills on Free, Pro, Max, Team and Enterprise. The developer docs list uploading custom skills in the app on Pro, Max, Team and Enterprise. If you are on Free and cannot find the upload button, that is the likely reason.

How do you add a skill to Claude Code?

Claude Code reads skills straight from folders. There is nothing to upload.

• For you, in every project: put the folder in ~/.claude/skills/, so the file sits at ~/.claude/skills/your-skill/SKILL.md.
• For one project and everyone working on it: put it in .claude/skills/ inside the repository and commit it.
• To use one now: type / and the skill’s name, like /your-skill. Claude also uses it by itself when your request matches the description.
• To see what is loaded: run /skills.

Claude Code picks up new and changed skills during the session, without a restart. If you create the skills folder itself mid-session, run /reload-skills. Claude Code also adds optional fields of its own. The most useful is disable-model-invocation: true, which means only you can start the skill, a good idea for anything with side effects, like a deploy.

To install Anthropic’s example skills in Claude Code, its GitHub repository gives two commands: /plugin marketplace add anthropics/skills, then /plugin install example-skills@anthropic-agent-skills. The document skills install the same way, as document-skills@anthropic-agent-skills.

How do you write your own Claude skill, step by step?

Claude Code’s docs give the best rule for when to bother: create a skill "when you keep pasting the same instructions" into chat. Here is a real one to copy. It turns a messy, spoken or typed idea into a short spec with fixed headings, so Claude stops guessing what you meant.

1. Pick one job you repeat

   One skill, one job. "Turn my rambling notes into a spec" is a good size. "Help with my work" is not.

2. Make the folder

   Name it after the skill, in lowercase with hyphens: writing-specs-from-voice-notes. Inside it, create a file called SKILL.md. Anthropic’s docs and its own repository spell it in capitals, so do the same.

3. Write the description first

   Say what it does, then when to use it, in the third person. Keep it under 200 characters. The developer docs allow 1,024, but the Help Center caps descriptions at 200 for skills uploaded in the app, so 200 works everywhere.

4. Write short rules and one example

   Claude is already smart. Write only what it cannot guess: your headings, your rules, and one example of good output.

5. Install it and try it

   In Claude Code, copy the folder into ~/.claude/skills/. For the app, zip the folder and upload it. Then try requests that should use it and some that should not.

Here is the complete file. The lines are short on purpose so it reads well on a phone.

---
name: writing-specs-from-voice-notes
description: >
  Turns a rambling voice note or
  dictated idea into a short, clear
  spec. Use when the user pastes a
  messy spoken request or asks for
  a spec or task list from notes.
---

# Voice note to spec

## Rules
- Keep every fact the user gave.
  Add nothing they did not say.
- When the user corrects
  themselves, keep only the
  last version.
- Drop filler, repeats and
  thinking out loud.
- Write in the user's language
  unless they ask for another.
- If something is missing, ask
  under Open questions.
  Never fill the gap yourself.

## Output
Use exactly these headings:

### Goal
One sentence.

### Must have
A numbered list, one item
per line.

### Rules and limits
What must not change or break.
Write "Not given" if none.

### Done when
How to check it works.
Write "Not given" if none.

### Open questions
Each gap, as a short question.

## Example
Input: "a booking page, name and
phone, no wait, email too, they
pick day and time, then a
confirmation email, I mean a
text, not an email"

Output:
### Goal
A booking page for customers.
### Must have
1. Fields: name, phone, email.
2. Pick a day and a time.
3. Confirm by text message.
### Rules and limits
Not given.
### Done when
Not given.
### Open questions
- Which days and times are open?
- How do we check it works?

Why each part is there:

• The description names the inputs people really bring ("a messy spoken request", "notes") so Claude matches it. It is 162 characters, under every limit.
• "Keep only the last version" handles the most common thing people do when they talk: correct themselves halfway.
• "Never fill the gap yourself" is the rule that makes the skill worth having. A spec that invents requirements is worse than no spec.
• The example shows the format once. Anthropic’s guide says examples show style "more clearly than descriptions alone."

A worked example: a real rambling request

This is the kind of input the skill is for. It is the demo request on our homepage, and the second part is what DanDin’s engine really wrote from it on 11 October 2026, in its "What I meant" mode, with Cursor as the app in front.

As said: ok so I want a booking page, like with name and phone, no wait, and email too, and the customer picks the day and time, and after booking they get a confirmation email, I mean a text, not an email.

DanDin’s real output: I need a booking page that collects the customer's name, phone number, and email address. The page should allow users to select a date and time for their appointment. Once the booking is complete, the system should send a confirmation via text message.

The cleaned version already applies the correction (a text, not an email). What it cannot add is what the speaker never said: there is no way to check the page works. That is exactly the gap the skill sends to Open questions. Give the skill either version and it should sort the facts under the five headings and ask about the rest. We have not published a scored test of this skill, so read what it gives you before you build on it.

What do Anthropic’s best practices say?

Anthropic’s authoring guide is long. These are the rules that matter most, in its own words where the words are short.

• Be brief. "The context window is a public good." Claude is already smart, so cut every line it could guess.
• Write the description in the third person. "Processes Excel files", not "I can help you". The description goes into Claude’s instructions, and a mixed point of view hurts matching.
• Say what and when. Every good example in the guide ends with "Use when..." and the words a user would type.
• Name it by the activity. The guide suggests the "-ing" form, like processing-pdfs. Avoid vague names like helper or utils.
• Keep SKILL.md under 500 lines. Move long material into separate files, and link each one straight from SKILL.md, only one level deep.
• Match freedom to risk. Loose guidance for open tasks, exact scripts for fragile ones like a database migration.
• Test before you write a lot. Build three test requests first, see where Claude fails without the skill, then write just enough to fix it.
• Use two Claudes. One helps you write the skill, a fresh one uses it on real tasks, and you bring what you see back to the first.
• Use forward slashes in file paths, even on Windows, and leave out anything that will go out of date.

Which example skills does Anthropic publish?

Anthropic keeps its own skills in a public GitHub repository. Its README says they are "for demonstration and educational purposes only", so test them before you rely on them. The ones most worth reading, with what each one’s own description says:

• skill-creator: helps you create, edit and test skills, including tuning a description so it triggers.
• doc-coauthoring: a guided workflow for writing docs, proposals and technical specs together.
• webapp-testing: tests local web apps with Playwright, with screenshots and browser logs.
• mcp-builder: a guide to building MCP servers in Python or TypeScript.
• frontend-design: visual direction for building a new interface that does not look like a template.
• internal-comms: status reports, leadership updates and newsletters in a company’s own formats.
• brand-guidelines: applies Anthropic’s own colors and type. Copy the pattern for your brand.
• docx, xlsx, pptx and pdf: the skills behind Claude’s file features. The README says these are "source-available, not open source", unlike most of the repository, which is Apache 2.0.

Are Claude skills safe to install?

Treat a skill like software, because it can be. Anthropic’s docs say to use skills only from trusted sources, meaning ones you wrote or got from Anthropic, because a bad skill can make Claude run tools or code in ways that do not match what it claims to do. Before you install someone else’s skill:

• Read every file in it, not only SKILL.md. Look for network calls or file access the skill has no reason for.
• Be extra careful with skills that fetch content from the web, since that content can carry hidden instructions.
• Never put an API key or password inside a skill. The Help Center says so too.

Talk your skills and tasks to Claude

DanDin is our product, so read this part with that in mind. The hard part of a good skill is not the format. It is explaining how you really work: the steps, the exceptions, the example. Most people can say that faster than they can type it.

DanDin (dandin.com) is a dictation app for Mac and Windows, built for Arabic and English. Hold Fn on a Mac, or Ctrl and the Windows key on a PC, talk, and let go. Clean text lands where your cursor is: the Claude app, a SKILL.md open in your editor, or Claude Code in your terminal. It drops the "ums", applies your corrections and adds punctuation. Speak Arabic, English or both, and a "Translate to English" switch hands Claude English when you speak Arabic. The free plan is 2,000 words every seven days. It needs the internet and has no phone app.

If you give Claude Code its tasks out loud, our guide on how to talk to Claude Code covers the structure that works and the one paste rule to know. For mixed Arabic and English speech, see Arabic and English in one dictation.