Claude Skills: the complete guide to what they are, where they work and how to make one

What are Claude Skills?

Claude Skills are folders of instructions, scripts and resources that Claude loads on its own when a task calls for them. Each skill is built around one file, SKILL.md, with a name, a description of when to use it, and step by step instructions in Markdown.

Anything else the skill needs, such as templates, reference documents or scripts, sits in the same folder and is opened only when the instructions point to it.

You don't have to call a skill by hand. Claude keeps a short list of every installed skill's name and description, and when your request matches one, it reads that skill's full instructions and follows them. That is the main difference from a saved prompt: a prompt waits for you to paste it, a skill is picked up when the task fits.

Skills work in the Claude app at claude.ai, in Claude Code, in the Claude API and in the Claude Agent SDK. Anthropic's documentation calls them Agent Skills, and in December 2025 Anthropic published the format as an open standard, which is why the same folder also works in OpenAI's Codex and other agents.

How a skill works: progressive disclosure

Skills are cheap to keep around because Claude loads them in three stages, only as far as the task needs. Anthropic's Agent Skills overview describes it like this:

So you can install dozens of skills without filling Claude's context window. The description is what Claude compares your request against, which makes it the most important line in the file.

A skill folder looks like this:

pdf-forms/
├── SKILL.md          required: header + instructions
├── FORMS.md          optional: extra guidance, read only when needed
└── scripts/
    └── fill_form.py  optional: code Claude runs instead of rewriting it

Where do Claude Skills work?

Skills run everywhere Claude can use a computer: the Claude app, Claude Code, the Claude API and the Claude Agent SDK. Each surface installs and shares them differently. Custom skills do not sync between surfaces by default: a skill uploaded to the Claude app is not available in the API, and the reverse.

The built-in document skills are what power Claude's ability to create and edit Word, Excel, PowerPoint and PDF files. In the Claude app they turn on by themselves whenever you ask for one of those files.

Use skills in the Claude app

Anthropic's help center lists skills on Free, Pro, Max, Team and Enterprise plans. They need code execution, because a skill is a folder Claude reads and runs inside a sandbox. (Anthropic's developer docs list custom skill uploads on Pro, Max, Team and Enterprise, so if you don't see the upload option on Free, that's why.)

Turn skills on

1. Open Settings > Capabilities and turn on Code execution and file creation.
2. Open Customize > Skills and switch on the skills you want.
3. On Team and Enterprise plans, an owner first goes to Organization settings > Plugins & skills, opens the Policy tab and enables both code execution and Skills. Members then switch skills on for themselves.

Upload your own skill

1. Build the skill folder with a SKILL.md inside (see Make your own skill below).
2. Zip it so the folder itself is at the root of the ZIP, not its contents.
3. Go to Customize > Skills, click +, choose + Create skill, then Upload a skill.
4. Upload the ZIP and switch the skill on.
5. Try a few requests that should trigger it. If Claude doesn't use it, make the description more specific and upload again.

release-notes.zip
└── release-notes/
    ├── SKILL.md
    └── references/
        └── style.md

The most common upload errors, per Anthropic's Using skills in Claude article, are a ZIP that's too large, a folder name that doesn't match the skill name, a missing SKILL.md, and invalid characters in the name or description.

Uploaded skills are private to your account. On Team and Enterprise plans you can share a skill with specific people from its menu once an owner has turned sharing on, and members can submit skills they created to the organization's library, where an owner may review them first. To remove a skill, switch it off, open the menu next to the toggle and choose Delete.

Use skills in Claude Code

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

• Personal skills, in every project: ~/.claude/skills/<name>/SKILL.md
• Project skills, shared through the repo: .claude/skills/<name>/SKILL.md
• Plugin skills, from installed plugins, named like /plugin-name:skill-name

Claude picks a skill when your request matches its description, and you can run one yourself by typing a slash and its name, like /release-notes. Older custom commands in .claude/commands/ still work; they have been merged into skills. Claude Code also adds optional header fields that other tools ignore, such as disable-model-invocation: true for skills you only want to run by hand. The full list is in the Claude Code skills docs, and our Claude Code skills guide covers installing skills from GitHub.

If you sign in to Claude Code with your Claude account, recent versions (v2.1.273 or later) download the skills you turned on in the Claude app into ~/.claude/skills/synced/ and check for changes while you work. The sync is one way: edits you make to those files locally are not sent back to claude.ai. It doesn't run when you sign in with an API key.

Use skills with the Claude API

In the API, skills run inside the code execution tool's container. You list the skills you want in the container parameter and include the code execution tool:

import anthropic
from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Upload a custom skill once. It is shared with your whole workspace.
skill = client.skills.create(files=files_from_dir("release_notes"))

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": skill.id, "version": "latest"},
        ]
    },
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[{"role": "user", "content": "Turn these merged PRs into release notes"}],
)

A few limits from the Skills API guide are worth knowing before you build on it:

• Up to 20 skills per request.
• A custom skill upload must stay under 30 MB uncompressed.
• The container has no network access and you can't install packages at runtime, so a skill can only use what's already installed.
• Each new version is a full snapshot: upload every file again, then pin a version ID or use latest.

Make your own skill

You don't need any tooling to write a skill. A text editor is enough.

1. Pick one task you repeat. "Write release notes from merged PRs" is a good skill. "Help with my job" is not.
2. Create a folder named in lowercase with hyphens, like release-notes.
3. Add SKILL.md with a header and numbered instructions.
4. Write the description last. Say what the skill does and when to use it, using the words you'd actually type.
5. Move long material out. Style guides, checklists and API notes go in separate files that SKILL.md links to.
6. Install and test it in Claude Code, or zip and upload it to the Claude app, then try three or four real requests.

Here is a complete skill you can copy:

---
name: release-notes
description: Draft release notes from merged pull requests, grouped as New,
  Improved and Fixed. Use when the user asks for release notes, a changelog
  or "what shipped" since the last release.
---

# Release notes

1. List the pull requests merged since the last tag.
2. Group them as New, Improved and Fixed. Skip refactors, tests and
   dependency bumps unless users will notice them.
3. Write one line per change, from the user's point of view, starting
   with a verb: "Add dark mode to the settings page."
4. Put breaking changes first, under a "Breaking" heading, with what
   users must do.

If no tag exists, ask which commit or date to start from.

You can also ask Claude to write the skill. Anthropic's best practices note that Claude handles the skill format natively: work through the task once in a normal chat, then ask Claude to turn what you just did into a skill, and trim what it writes. Anthropic's open source skill-creator skill goes further and helps test and tune the description. Anthropic's longer Complete Guide to Building Skills for Claude covers planning, testing and distribution in depth.

For a step by step walkthrough of the format, read how to write a SKILL.md. For more finished files to start from, see 14 Claude skills examples. And if you already have a prompt that works, the free SKILL.md generator turns it into a valid skill in your browser.

Name and description rules

The open standard sets the basic rules, and Claude adds a few of its own. Follow the stricter set and your skill will load everywhere.

Anthropic's authoring best practices add two more habits: keep the body of SKILL.md under 500 lines, and keep reference files one level deep, linked straight from SKILL.md.

Why doesn't Claude use my skill?

Almost every "my skill doesn't work" problem is a description problem. Work through these in order:

1. Check that it loaded. In Claude Code, ask "What skills are available?" or run /skills. In the Claude app, check the skill is switched on in Customize, Skills.
2. Rewrite the description with real trigger words. If you ask for "a changelog" but the description only says "release notes", Claude may not connect them. Name both.
3. Check the header parses. In Claude Code, a broken YAML header still loads the body, but with no description, so Claude can't match it. Run claude --debug to see the error.
4. Run it by hand with /skill-name in Claude Code to confirm the instructions themselves work.
5. If it fires too often, make the description narrower, or add disable-model-invocation: true in Claude Code so it only runs when you call it.

Skills compared with prompts, Projects, MCP and subagents

Claude has several ways to give it context. They solve different problems and often work together.

Anthropic's own summary is a good rule: MCP connects Claude to data, skills teach Claude what to do with that data. The full comparison is in skills vs MCP.

Use skills safely

A skill is instructions plus code, so treat installing one like installing software. Anthropic recommends using skills only from sources you trust, such as ones you wrote or ones from Anthropic. Before you turn on a skill from somewhere else, read every file in it, scripts included, and look for anything that calls the network or touches files unrelated to its stated job. Be most careful with skills that fetch content from outside URLs, since that content can change after you've reviewed it.

Keep your skills in one place

Skills start life as prompts you keep retyping, and they end up scattered: some in ~/.claude/skills/, some in a project, some only in the Claude app. Kipt keeps your prompts and skills together in a private GitHub repo you own. Paste a prompt to save it, press ⌘K to find it, and choose Promote to skill to turn it into a valid SKILL.md in the same repo. Every skill then installs into Claude Code or Codex with one command, npx skills add https://github.com/<you>/<repo>.git, on any computer.

New to the format? Start with the free SKILL.md generator, or browse ready-made ones in the best Claude Code skills list.