How to Create a Claude Skill: 2026 Step-by-Step Guide

Anthropic engineers told the public in April 2026 that they now use "hundreds" of internal Claude Skills in production — and the format itself is almost embarrassingly simple: a folder, one markdown file, two required YAML fields. Yet most first attempts fail. Not because the syntax is hard, but because Claude never invokes them.

This guide walks through the entire process from idea to working skill, using the same structure Anthropic's own document-creation skills use, and surfaces the specific failure modes the team has flagged internally. By the end you will have built and tested a working SKILL.md, picked the right platform to deploy it on, and know how to debug the most common reason skills do not trigger.

In short: A Claude Skill is a folder containing a single SKILL.md file with two required YAML fields — name and description — plus markdown instructions Claude follows when the skill is triggered. Build it in any text editor, ZIP the folder, then upload via Customize → Skills in claude.ai. The description field decides whether your skill ever runs, which is why it deserves more attention than the instructions themselves.

What Is a Claude Skill?

A Claude Skill is a folder of instructions, scripts, and reference files that Claude loads on demand to perform a specific task in a repeatable way. Anthropic describes them as a way to teach Claude how to complete specialized work — applying brand guidelines, running a sprint report, generating lesson plans — without re-explaining the workflow every time.

The minimum viable skill is a directory containing one file: SKILL.md. According to the official Claude support documentation published in March 2026, every skill consists of a directory containing at minimum a SKILL.md file that must start with YAML frontmatter holding name and description as required metadata fields. Everything else — additional files, scripts, executable code, reference documents — is optional and loaded only when Claude decides it needs them.

Skills work through what Anthropic calls "progressive disclosure." The metadata (name + description) is read first to decide whether the skill is relevant. The markdown body is loaded second, only if the skill is invoked. Reference files referenced inside the body are loaded third, only when Claude actively needs them. The design keeps context windows efficient while letting one skill carry a lot of knowledge.

As of May 2026, custom Skills are available on Free, Pro, Max, Team, and Enterprise plans on claude.ai, with code execution required to enable them. They are also available in beta in Claude Code and for all users of the Claude API with the code execution tool enabled.

Claude Skills vs Projects vs MCP vs System Prompts: Which One Should You Use?

A Skill is not the right tool for every customization. Pick the wrong primitive and you will either over-engineer or hit a capability wall. Use this decision matrix:

The simplest test: if the task needs live external data, you want MCP. If it needs shared context across many chats, you want a Project. If it is a workflow you describe in plain text, you want a Skill. If it is how you want Claude to write to you in general, you want Custom Instructions.

A skill can call MCP tools and live inside a Project, so these primitives compose. They do not replace each other.

How to Create a Claude Skill (Six Steps)

The full process takes 20 to 30 minutes for a first skill, and most of that is testing. Here is the end-to-end build for a worked example: a Sprint Report Generator that turns a week of work notes into a structured status update.

Step 1. Pick one repeatable task

A good skill solves a focused, recurring task. Anthropic's official best-practice guidance is to keep skills focused on one workflow rather than trying to do everything, and to create separate skills for different workflows rather than one large skill that tries to handle every case.

Bad first skills: "help with my job," "improve my writing," "be a marketing expert." Each of those is a personality, not a task.

Good first skills: "turn raw sprint notes into a Friday update in our team format," "convert a transcript into LinkedIn post + tweet thread + newsletter blurb," "review a pull request description and add the test plan section we always forget."

The test: can you describe both the trigger (when should this run?) and the output (what should it produce?) in one sentence each? If yes, you have a skill-shaped problem.

Step 2. Create the folder and SKILL.md

Make a directory named after your skill. The folder name will become part of the install package, and Anthropic recommends matching it to your skill name.

sprint-report-generator/
└── SKILL.md

Open SKILL.md in any text editor — VS Code, Sublime, plain Notepad, anything. The file is just markdown.

Step 3. Write the frontmatter

Frontmatter is the YAML block at the very top of the file, fenced by three dashes on each side. Two fields are required: name and description.

---
name: sprint-report-generator
description: >
  Turn raw sprint notes, Slack updates, and Linear ticket lists into a structured
  Friday status report following the team's "wins / risks / asks" format.
  Use whenever the user shares notes from a sprint and asks for a status update,
  weekly report, Friday update, or stakeholder summary.
---

A few rules from the official documentation: name has a 64-character maximum, description has a 200-character maximum (the multi-line > block in YAML lets you write naturally while staying under the limit), and YAML is whitespace-sensitive — use two spaces for indentation, never tabs.

Step 4. Write the instructions

Everything below the closing --- is what Claude reads after deciding to invoke the skill. Write it the way you would brief a competent new hire: clear, specific, and with examples.

# Sprint Report Generator

You are turning raw sprint notes into a Friday status report.

## Required output structure

Use exactly these three H2 sections, in this order:

1. **Wins** — what shipped, with the linked ticket or PR.
2. **Risks** — what is at risk for next sprint, with the owner and the
   specific mitigation being considered.
3. **Asks** — what the team needs from stakeholders this week, each phrased
   as a single sentence with a clear deadline.

## Style rules

- Keep each bullet under 25 words.
- Lead with the verb, not the subject ("Shipped X" not "We shipped X").
- Cite tickets in the format PROJ-1234, not full URLs.
- If a section has no items, write "None this week" rather than removing
  the heading.

## Example

INPUT:
"this week we got the auth refactor live, finally. mike's still
worried about the database migration scheduled for next sprint —
he wants more time. need design sign-off on the new dashboard by tue."

OUTPUT:

## Wins

- Shipped the auth refactor (PROJ-1842).

## Risks

- Database migration scheduled for next sprint is at risk per Mike;
  mitigation being discussed is splitting the migration over two sprints.

## Asks

- Design sign-off on the new dashboard needed by Tuesday.

Anthropic's authoring guidance is to include examples of input and output whenever you can, because Claude uses them to understand what success looks like.

Step 5. Test locally before packaging

Before you ZIP anything, paste the whole SKILL.md into a fresh chat with Claude and write the prompt you expect to trigger the skill in production. If Claude produces the output your instructions describe, the body is good. If it produces something close but different, your instructions need more specificity. Test incrementally rather than building a complex skill in one go.

Step 6. Package and upload

Once your folder is finished:

1. Verify the folder name matches your skill name (sprint-report-generator).
2. Create a ZIP file of the folder. The ZIP should contain the folder as its root, not the files directly.
3. In claude.ai, go to Settings → Capabilities → Skills, click Upload Skill, and select the ZIP.
4. Enable the skill in Customize → Skills.

Correct structure:

sprint-report-generator.zip
└── sprint-report-generator/
    └── SKILL.md

Incorrect (files in the ZIP root with no parent folder) will throw a YAML or frontmatter error on upload.

The Description Field Is 90% of the Work

This is the part most tutorials skip, and it is where most first skills fail.

A Claude Skill auto-invokes when the description in its frontmatter matches what the user is asking. If the description is vague, the skill never fires. If the description is too broad, it fires on every request and pollutes context. The body of the skill could be perfect and it will not matter, because Claude never gets there.

An Anthropic engineer writing in April 2026 noted that Claude has a tendency to "under-trigger" skills — to not use them when they would be useful — and that descriptions should be written in a slightly "pushy" style to counter that bias.

Apply this four-part test to every description you write:

A description that fails the test:

description: Helps with sprint reports.

A description that passes:

description: >
  Turn raw sprint notes, Slack updates, and Linear ticket lists into a
  structured Friday status report following the team's "wins / risks /
  asks" format. Use whenever the user shares notes from a sprint and asks
  for a status update, weekly report, Friday update, or stakeholder summary.

If your skill is not triggering after upload, rewrite the description before you touch anything else.

Where to Deploy Your Skill: claude.ai vs Claude Code vs API

The same SKILL.md will run on three different surfaces, but the deployment and capabilities differ. Pick based on the user, not the technology.

Critical detail for Claude Code: the frontmatter has more configurable fields than the claude.ai version supports. Fields like allowed-tools, disable-model-invocation, user-invocable, and per-skill model selection are Claude Code features. A skill written for Claude Code with those fields will still work in claude.ai, but the extra fields are ignored.

If you want your skill to run anywhere, write the frontmatter using only name and description. Add platform-specific fields only when you actually need them.

Five Common Mistakes (and How to Avoid Them)

These are the failure modes most likely to bite a first-time skill author, drawn from Anthropic's published authoring guidance and from practitioners who have shipped multiple skills:

1. Writing a skill that is really a personality. "Be a marketing expert" is not a workflow — it is an identity. Skills work when they encode a task with steps, not a persona. Move identity preferences to Custom Instructions and keep the skill scoped to a workflow.

2. Hardcoding sensitive information in the SKILL.md. Anthropic's security guidance is explicit: do not hardcode API keys, passwords, or credentials. If your skill needs to call an external service, use an MCP connection or pass secrets at runtime through your own infrastructure.

3. Treating skills as if they were just markdown files. They are folders. According to Anthropic's internal guidance from April 2026, the most powerful skills use scripts, reference files, and supporting assets that the agent can discover and use. If your SKILL.md is getting long, split sections into reference files like REFERENCE.md and let Claude load them on demand.

4. Filling the body instead of sharpening the description. Every line in the body is a recurring token cost once the skill loads, and a long body cannot rescue a description that does not trigger. Time spent on the description has higher ROI than time spent on the body, until the description passes the four-part test above.

5. Skipping the "Gotchas" section. Practitioners writing for Anthropic in April 2026 noted that the most valuable content in any skill is the Gotchas section — a list of common mistakes the skill should avoid. It works because it tells Claude what not to do, which is harder to infer than what to do. Always include one.

FAQ

How long does it take to create a Claude Skill?

A first skill takes 20 to 30 minutes end-to-end: 5 minutes to write the SKILL.md, 10 to 15 minutes to test and refine the description until it triggers reliably, and 5 minutes to package and upload. Subsequent skills are faster because you reuse the structure.

Do I need to know how to code to create a Claude Skill?

No. A basic skill is a single markdown file with a YAML header. Anthropic's official guidance recommends starting simple with plain markdown instructions before adding scripts. You only need code if your skill performs operations Claude cannot do in natural language, such as parsing a specific file format or calling an external API.

What is the difference between a Claude Skill and a Claude Project?

A Project is a workspace that holds shared context — documents, chat history, instructions — for a bounded body of work, and the user picks it when starting a chat. A Skill is a reusable workflow Claude auto-invokes across any chat when the description matches the request. Projects scope context; skills scope tasks.

Can I share a Claude Skill with my team?

Yes, on Team and Enterprise plans. Custom skills on Pro and Max plans are individual to each user, but Team and Enterprise administrators can provision skills organization-wide following Anthropic's published provisioning guide. On any plan you can also share the skill ZIP directly with a colleague who uploads it themselves.

Why is my Claude Skill not triggering?

The description is almost always the cause. Claude reads only the name and description to decide whether to invoke a skill, so if either is vague, generic, or written as a personality rather than a task, Claude will not load the skill body. Rewrite the description using the four-part test (what, when, scope, length) before changing anything else.

Are Claude Skills free?

Yes. Custom skills are available on every plan including the free tier, provided code execution is enabled in the account settings. Anthropic does not charge a separate fee for skill usage; standard plan limits apply.

Can a Claude Skill call external APIs or read files?

Yes, when paired with the right tools. Skills can include executable scripts in Claude Code and the API, and can call MCP servers for live external data such as Gmail, Linear, or a custom database. For external calls, configure the MCP connection separately and reference it from the skill body rather than hardcoding credentials.

Conclusion: Build One This Week

The best way to learn the format is to ship a skill you will actually use. Pick the most boring repeating task on your calendar this week — the weekly report, the meeting recap, the standup summary — and convert it into a SKILL.md. Use the four-part description test, keep the body short, and upload it before the next time you would have done the task by hand. The second skill is always easier than the first, and the gap between "I have read about skills" and "I have shipped one" is the only one that matters.