How to Create a Claude Skill (Step-by-Step, with a Free Template)

To create a Claude skill, you write one folder with one file in it: a SKILL.md that starts with a name and a description, followed by plain-language instructions. Zip the folder, upload it in Claude (or drop it into ~/.claude/skills/ for Claude Code), and Claude will load it whenever a request matches the description. No code, no SDK, no build step.

That is the whole mechanism. What separates a skill that fires every time and produces work you can ship from one that never triggers is about six decisions, and this guide walks through them in order. At the end there is a free template you can copy, and a checklist to test your skill before you rely on it.

If you are new to the idea itself, start with What Are Claude Skills? and come back. This page assumes you know what a skill is and want to build one.

What you need before you start

• A Claude account with code execution turned on. Skills run on Free, Pro, Max, Team and Enterprise plans, but the setting for code execution and file creation has to be enabled. On Team and Enterprise an admin may need to switch skills on for the organisation first.
• A text editor. Anything that saves plain text: VS Code, TextEdit in plain-text mode, Notepad.
• One repeatable task. Not "marketing". Something like "turn a sales call transcript into a CRM note in our format" or "review a contract for our five standard red flags". The narrower the job, the better the skill.
• Two or three real examples of good output. Past reports, emails, briefs that you would be happy to send. These are the single best raw material for a skill.

Step 1: Pick one job and define "done"

Most failed skills fail here, before a line is written. A skill that tries to cover "everything a marketing manager does" ends up with a vague description, fires at the wrong moments, and gives generic answers when it does fire.

Write two sentences before anything else:

1. The trigger: "Use this when someone asks for X or hands over Y."
2. The deliverable: "The output is a Z with these sections, in this length, in this tone."

Example: "Use this when someone pastes a customer call transcript and asks for notes. The output is a CRM note with Summary, Pain points, Budget, Next step and Risk, under 200 words, written for a sales manager who was not on the call." If you cannot write those two sentences, split the job into two skills.

Step 2: Create the folder and the SKILL.md file

A skill is a folder whose name matches the skill name. Inside it, the only required file is SKILL.md (the file name is case-sensitive). Optional extras go next to it:

Keep the folder name lowercase with hyphens, like call-notes or quarterly-report. The same string goes in the name field in the next step.

Step 3: Write the frontmatter (the part that decides when it fires)

The file opens with a short YAML block between two lines of three hyphens. Two fields are required:

• name - lowercase letters, numbers and hyphens, up to 64 characters. It becomes the identifier, and in Claude Code the slash command (/call-notes).
• description - up to 1,024 characters. This is the only part Claude reads for every installed skill at the start of a session. It decides whether your skill gets loaded at all.

Write the description the way you would brief a colleague who has to decide in one second whether a request is theirs. Lead with what the skill produces, then list the situations and phrases that should wake it up. Compare:

• Weak: "Helps with sales notes."
• Strong: "Turns a sales or discovery call transcript into a structured CRM note (Summary, Pain points, Budget, Next step, Risk) under 200 words. Use when the user pastes a call transcript, meeting recording text or rough call notes and asks for notes, a recap, a CRM entry or a follow-up summary."

The strong version names the input, the output, and the words people actually type. That is what makes it trigger reliably and stay quiet the rest of the time.

Step 4: Write the instructions as a method, not a mood

Everything below the frontmatter is Markdown that Claude follows once the skill loads. The common mistake is a long persona ("You are a world-class sales expert with 20 years...") and no procedure. Claude does not need a backstory. It needs steps, rules and a target format. A structure that works for most business skills:

1. Inputs - what the user will provide and what to ask for if it is missing (maximum two questions, then proceed with stated assumptions).
2. Workflow - numbered steps in the order a careful professional would do them.
3. Output format - the exact sections, headings, length and tone.
4. Rules - the things that must always or never happen ("never invent a budget figure; write 'not discussed'").
5. Quality check - a short list Claude runs through before answering.

Aim for something that fits on one or two screens. If the file runs past roughly 500 lines, move reference material (long style guides, price lists, policy text) into files under resources/ and tell Claude in SKILL.md when to open them. Claude loads those extra files only when the task needs them, which keeps the context light. For more on how the file is structured, see What Is a SKILL.md File?

Step 5: Add one example of finished output

An example teaches format faster than any amount of description. Put one realistic, finished deliverable in resources/example-output.md and reference it from the workflow ("match the structure and length of resources/example-output.md"). Use a real past piece of work with names and figures changed, not a placeholder full of brackets. Our own catalogue follows the same rule: every skill ships with an example output, because it is the clearest sign someone actually tested the thing.

Step 6: Package and install it

In Claude (web and desktop): zip the folder so that the folder itself sits at the root of the zip (call-notes.zip containing call-notes/SKILL.md). Open the skills section in your settings, upload the zip, and toggle the skill on. Start a new chat and make a request that matches the description.

In Claude Code: no zip needed. Put the folder in ~/.claude/skills/ to use it in every project, or in .claude/skills/ inside a repository to share it with everyone working on that repo. Type /call-notes or just describe the task. Claude Code picks up changes to the folder without a restart.

The full walkthrough for each surface, including where the files live and what to do when an upload is rejected, is in How to Install a Claude Skill. Developers who work mostly in the terminal should also read Claude Code Skills.

Step 7: Test it like you mean it

A skill that has only been tried once has not been tested. Run this check before you share it with a team:

1. Trigger test (5 prompts). Write five requests that should fire the skill, phrased differently. Count how many do. Fewer than four means the description needs more of the user's real wording.
2. Silence test (5 prompts). Write five nearby requests that should not fire it. If it fires on any, narrow the description.
3. Missing-input test. Give it half the inputs. It should ask a short question or state its assumptions, not invent facts.
4. Format test. Compare three outputs side by side with your example. Same sections, same length band, same tone?
5. Edge-case test. Feed it the messiest real input you have: a rambling transcript, a half-empty spreadsheet.

Fix the description for trigger problems and the workflow or rules for output problems. Keep a short changelog at the bottom of the file so you know which version your team is running.

Free Claude skill template (copy and adapt)

Replace the parts in capitals, delete what you do not need, and save it as SKILL.md inside a folder with the same name as the name field.

---
name: your-skill-name
description: Produces A SPECIFIC DELIVERABLE (sections, length) from A SPECIFIC INPUT. Use when the user ASKS FOR X, PASTES Y, or mentions Z. Do not use for NEARBY TASK THAT BELONGS ELSEWHERE.
---

# YOUR SKILL TITLE

## Purpose
One or two sentences: who this is for and what "done" looks like.

## Inputs
- Required: WHAT THE USER MUST PROVIDE
- Optional: WHAT IMPROVES THE RESULT
- If a required input is missing, ask at most two short questions,
  then proceed and list your assumptions at the top of the output.

## Workflow
1. Read the input and identify KEY ELEMENTS.
2. Check it against RULES OR CRITERIA.
3. Draft the output in the format below.
4. Run the quality check, fix anything that fails, then answer.

## Output format
- Section 1: NAME - WHAT GOES HERE (length)
- Section 2: NAME - WHAT GOES HERE (length)
- Section 3: NAME - WHAT GOES HERE (length)
Match the structure and length of resources/example-output.md.

## Rules
- Never invent figures, names or dates. Write "not provided" instead.
- Use plain English. No filler openings.
- RULE SPECIFIC TO YOUR TEAM OR INDUSTRY.

## Quality check
- Every section present and in order?
- Every claim traceable to the input?
- Within the length limit?

## Changelog
- v1.0 FIRST VERSION, DATE

Want to see what finished skills look like? Claude Skill Examples walks through twelve real SKILL.md files line by line, which is the fastest way to calibrate how much detail is enough.

Five mistakes that make a skill useless

• A description that says what the skill is, not when to use it. "An expert copywriter" never triggers. "Writes product page copy from a feature list when the user asks for a product description, PDP copy or listing text" does.
• One skill for a whole department. Budgeting, payroll and audit in one file give you three half-answers. Make three skills.
• No output format. Without one, every run looks different and nobody trusts it.
• Secrets in the file. Never paste API keys, passwords or client data into a skill. Anyone you share it with can read it.
• Installing someone else's skill unread. A skill is instructions Claude will follow, sometimes with scripts. Read it the way you would read a script before running it.

Let Claude write the first draft for you

You do not have to start from a blank file. Claude can interview you about the task, draft the frontmatter and workflow, generate an example output and propose the test prompts above. Anthropic ships a built-in skill-creator skill for exactly this, and you can also ask in plain words: "Interview me about how I write our weekly client report, then write a SKILL.md for it." The draft will need your edits, especially the description and the rules, but it removes most of the typing.

Prefer a form to a chat? The free Claude Skill Builder turns a short description of the task into a ready SKILL.md with frontmatter and a workflow, which you can copy or download as a .zip for Claude.ai and Claude Code. No sign-up.

Want the interview, the self-test and the packaging done for you? Claude Skill Creator ($7) is a skill that builds skills: it asks about the job, the requests people actually type and what must never happen, writes a complete skill folder with the SKILL.md and an example output, tests the description against requests that should and should not trigger it, and packages the folder for Claude, Claude Code and the API. To audit a skill you wrote or downloaded, use the Claude Skill Reviewer & Security Linter, or get both, plus prompt, MCP and code review skills, in the Build Your Own Claude Skills Kit ($19).

Build it yourself or start from a ready-made one?

Build your own when the workflow is unique to your team, when it encodes internal knowledge nobody outside has, or when you enjoy iterating. Start from a ready-made skill when the job is a standard role (bookkeeping, SEO briefs, contract review, support replies) and you would rather spend the afternoon on the work than on the instructions. A ready-made skill from our Claude skills library costs $7, comes with an example output, and is a plain Markdown file you can open and edit, so it also works as a starting template for your own version.

Either way, the next step is the same: pick one task you repeat every week, write the two sentences from Step 1, and have a working skill before the end of the day.