How to Create a Claude Skill: A Step-by-Step Guide With Examples

A Claude Skill is a folder that teaches Claude one of your repeatable workflows once, so it applies that workflow automatically every time it's relevant. If you're not yet sure what a skill is, start with our plain-English explainer on Agent Skills. This guide is the hands-on follow-up: how to actually build one, step by step, using Anthropic's own authoring guidance. You'll write a working skill by the end, and you don't need to be a developer to do it.

TL;DR

A skill is a folder with a SKILL.md file inside. That file has YAML frontmatter (a name and a description of what the skill does and when to use it) followed by Markdown instructions. Keep the body under 500 lines, write the description in the third person with specific trigger words, and move advanced detail into separate files that SKILL.md links to. The fastest way to build one is to do a task with Claude in plain conversation, notice what you keep re-explaining, then ask Claude itself to package that into a skill. Install it by dropping the folder into Claude Code, uploading a zip in Claude.ai settings, or posting it to the Claude API.

Before you start: build it from a real task

The single best piece of advice from Anthropic's authoring guide is counterintuitive: don't sit down to "write a skill." Instead, do the task with Claude normally first.

Work through a real problem in a regular conversation — say, drafting a client report. As you go, you'll naturally paste in context, explain your preferences, and correct Claude's output. Pay attention to what you keep repeating. That repeated context is the skill. This approach (Anthropic calls it evaluation-driven development) ensures you're solving a real problem instead of documenting an imagined one.

So before writing anything, run the task two or three times. Note where Claude needed guidance it didn't have. Those gaps are exactly what your skill will fill.

Step 1: Create the folder and SKILL.md

A skill is just a directory containing a file named SKILL.md. The smallest possible skill is one file:

my-skill/
└── SKILL.md

SKILL.md has two parts: a frontmatter block (metadata) and a body (instructions). Here's the complete shape:

---
name: writing-client-reports
description: Generates monthly client status reports in our standard format. Use when the user asks for a client report, status update, or monthly summary.
---
 
# Writing Client Reports
 
## Instructions
[step-by-step guidance for Claude]
 
## Examples
[a concrete example of a finished report]

That's a functioning skill. Everything else in this guide is about making it good.

Step 2: Write the name and description (the part that matters most)

Claude decides whether to use your skill based almost entirely on the description. If the description is vague, Claude won't reach for the skill at the right moment — and a skill that never triggers is useless. Get this right before anything else.

The name field rules:

• Lowercase letters, numbers, and hyphens only
• Maximum 64 characters
• Cannot contain the reserved words "anthropic" or "claude"

Anthropic recommends the gerund form (verb + -ing): writing-client-reports, analyzing-spreadsheets, processing-pdfs. Avoid vague names like helper, utils, or tools.

The description field — three rules that make or break discovery:

1. Say what it does AND when to use it. The description must contain the triggers. Compare:

   • Bad: description: Helps with documents
   • Good: description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

2. Write in the third person. The description is injected into Claude's system prompt, and mixing points of view causes discovery problems.

   • Good: "Processes Excel files and generates reports"
   • Avoid: "I can help you process Excel files" / "You can use this to process Excel files"

3. Include the specific words a user would actually say. If people ask for a "status update" or a "monthly summary," put those phrases in the description so Claude connects the request to the skill.

The description maxes out at 1,024 characters. Use that room to be specific rather than clever.

Step 3: Write a concise body

Once Claude loads SKILL.md, every word competes with the conversation for space. Anthropic's framing: "the context window is a public good." So the guiding rule is assume Claude is already smart, and only add what it doesn't already know.

Challenge every line: Does Claude really need this? Can I assume it already knows this? You don't need to explain what a PDF is or how a spreadsheet works. You do need to tell Claude your specific rules — your report format, your filtering conventions, the phrasing your brand uses.

A concise instruction:

## Generate the report
 
Pull the month's numbers, then fill this structure:
- Executive summary (one paragraph)
- Key wins (3 bullets, each with a metric)
- Risks and blockers
- Next month's priorities
 
Always exclude internal test accounts from the figures.

That last line — "exclude internal test accounts" — is the kind of thing Claude can't guess. That's what earns its place in the skill.

Keep the body under 500 lines. If you're approaching that, it's a signal to split content into separate files (Step 5).

Step 4: Match specificity to the task's fragility

Not every instruction should be equally rigid. Anthropic frames this as "degrees of freedom," with a useful analogy — think of Claude as a robot on a path:

• Open field (high freedom): Many valid approaches exist. Give general direction and trust Claude. Good for things like content drafting or code review, where context decides the best route.
• Narrow bridge with cliffs (low freedom): One safe way forward. Give exact, do-not-deviate instructions. Good for fragile, high-stakes, must-be-consistent operations.

In practice: for a flexible writing task, a numbered list of considerations is enough. For something that must run a precise sequence, be explicit — "Run exactly this command. Do not modify it or add flags." Loose instructions for fragile tasks cause errors; rigid instructions for open tasks waste Claude's judgment.

Step 5: Split into multiple files as it grows (progressive disclosure)

Skills load information in stages — this is the mechanism that keeps them efficient (covered fully in the Agent Skills explainer). When authoring, you put that mechanism to work by keeping SKILL.md as a lean overview that links out to detail Claude reads only when needed.

A skill that organizes data by domain might look like this:

bigquery-skill/
├── SKILL.md              (overview and navigation)
└── reference/
    ├── finance.md        (revenue, billing metrics)
    ├── sales.md          (pipeline, opportunities)
    └── product.md        (usage, adoption)

When someone asks about revenue, Claude reads SKILL.md, follows the link to reference/finance.md, and ignores the rest — the other files cost zero tokens until touched.

Two authoring rules make this work reliably:

• Keep references one level deep. Link from SKILL.md directly to each reference file. Don't make SKILL.md point to advanced.md, which points to details.md — Claude may only partially preview deeply nested files and miss information.
• Add a table of contents to any reference file over ~100 lines, so Claude can see the full scope even when previewing.

Step 6: Add scripts for things that must be exact (optional)

If your skill involves an operation that needs to be reliable every time — data validation, a file transformation, a precise calculation — bundle a script instead of asking Claude to write the code fresh each time. Pre-made scripts are more reliable, save tokens (the code never enters the context window — only its output does), and stay consistent across uses.

When you include a script, make the intent explicit:

• To run it: "Run analyze_form.py to extract the fields."
• To read it as reference: "See analyze_form.py for the extraction algorithm."

For most utility scripts you want execution, not reading. And for risky batch operations, Anthropic recommends a "plan → validate → execute" pattern: have Claude write a plan to a file, run a validation script against it, and only then apply the changes. This catches mistakes before they happen.

Two caveats on the runtime: scripts in the Claude API sandbox have no internet access and can't install packages, while scripts in Claude Code run with full access like any program on your machine. Always use forward slashes in file paths (scripts/helper.py), even on Windows.

Step 7: Let Claude write the skill for you

You don't need to hand-author the file. Claude understands the skill format natively. The most effective workflow uses two roles:

1. Work through the real task with one Claude conversation ("Claude A"), providing your context and corrections as you go.
2. Then ask: "Create a skill that captures the report workflow we just used. Include the format, the test-account filtering rule, and the tone." Claude A generates a properly structured SKILL.md.
3. Review it for conciseness — tell it to cut any explanation Claude would already know.
4. Test the skill in a fresh Claude conversation ("Claude B") on a similar task. Watch where it struggles.
5. Bring those observations back to Claude A to refine — e.g., "When I used this, it forgot the test-account filter. Make that rule more prominent."

This observe-refine-test loop, driven by real usage rather than guesses, is how good skills actually get built.

Step 8: Install it

Where you put the finished folder depends on which Claude surface you use:

• Claude Code — Drop the folder into ~/.claude/skills/ (personal) or .claude/skills/ (shared with a project). No upload step; Claude discovers it automatically.
• Claude.ai — Zip the folder and upload it under Settings → Features, available on Pro, Max, Team, and Enterprise plans with code execution enabled. Note: skills here are per-user; each teammate uploads their own.
• Claude API — Upload through the /v1/skills endpoints; skills are shared across the workspace.

Remember that skills don't sync across these surfaces — a skill uploaded to Claude.ai isn't automatically available in the API or Claude Code.

A quick quality checklist

Before you rely on a skill, run through Anthropic's essentials:

• The description says both what the skill does and when to use it, with specific trigger words
• The description is written in the third person
• SKILL.md body is under 500 lines
• Advanced detail lives in separate files, linked one level deep from SKILL.md
• Terminology is consistent (pick one word per concept and stick to it)
• No time-sensitive instructions that will quietly go stale
• Examples are concrete, not abstract
• You've tested it on a real task in a fresh conversation

Frequently asked questions

How do I create a Claude Skill?

Create a folder containing a SKILL.md file. Add YAML frontmatter with a name and a description of what the skill does and when to use it, then write Markdown instructions in the body. Install it by placing the folder in Claude Code, uploading a zip in Claude.ai settings, or posting it through the Claude API. You can also ask Claude itself to generate a properly structured skill from a task you just completed.

What goes in a SKILL.md file?

SKILL.md has two parts: YAML frontmatter at the top (a required name and description) and a Markdown body with instructions, examples, and any references to bundled files. The description is the most important field because Claude uses it to decide when to trigger the skill. Keep the body under 500 lines.

How do I write a good skill description?

State both what the skill does and when to use it, write in the third person ("Processes Excel files," not "I can help you"), and include the specific words a user would actually say when they need it. Avoid vague descriptions like "helps with documents." The description can be up to 1,024 characters.

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

No. A skill can be a single Markdown file of plain-English instructions with no code at all. Scripts are an optional add-on for operations that must run exactly the same way every time. You can also have Claude write the entire skill for you based on a task you walked through in conversation.

Where do I install a custom Skill?

In Claude Code, place the folder in ~/.claude/skills/ (personal) or .claude/skills/ (per project). In Claude.ai, upload a zip under Settings → Features on a paid plan with code execution enabled. Via the Claude API, upload through the /v1/skills endpoints. Skills do not sync across these surfaces, so install separately where you need them.

How long should a SKILL.md file be?

Keep the body under 500 lines for best performance. If you're approaching that limit, split the content into separate reference files and link to them from SKILL.md, keeping every reference one level deep. Only include information Claude doesn't already know — assume it's already capable and avoid explaining basics.

Build one this week

The best way to learn this is to ship a real skill. Pick one task you hand Claude over and over — a report, a brand-voice rewrite, an onboarding sequence — walk through it once in conversation, then ask Claude to package it. You'll have a working skill in an afternoon.

If you want a grounding in using Claude well at work before you start packaging skills, the free Claude Cowork course covers real prompts and workflows built for operators and small teams, not developers. It's a free download.