$ skilldirectory
— zsh — registry.skilldirectory.dev
skill libraryblogguidesabout

home / blog / claude skills

How to Create Claude Skills: Step-by-Step Guide With a Template (2026)

Quick answer: Create a folder, add a SKILL.md file with a name, a description and instructions, then place it where Claude looks for skills.

The description is the most important part, because Claude uses it to decide when your skill applies.

A Claude skill is a folder with one required file, SKILL.md. You can write a useful one in about ten minutes, with no code.

This guide walks through eight steps and ends with a template you can copy. New to the idea? Start with what Claude skills are.

What you need

  • A task you repeat and want done the same way each time.
  • A text editor.
  • Claude Code, Claude.ai or the API to run the skill.

You do not need to write code. Scripts are optional, and most good skills are plain instructions.

How to create a Claude skill in 8 steps

1. Pick one repeatable task

Start narrow. A skill that does one job well beats one that tries to do everything.

Write down two or three real requests you would type, for example "draft a blog post about X". These become your test cases later.

2. Create the folder

Make a folder named for the skill, using lowercase letters, numbers and hyphens, such as blog-post-writer. Inside it, create a file called SKILL.md.

In Claude Code, the folder name should match the name you set in the file.

3. Add the frontmatter

SKILL.md starts with a short settings block between two lines of three dashes. Two settings are required.

SettingRules
nameLowercase letters, numbers and hyphens, up to 64 characters. Avoid the words "claude" and "anthropic"
descriptionNot empty, up to 1,024 characters, no XML tags. Say what the skill does and when to use it

4. Write a good description

The description is how Claude decides whether to load your skill. Claude reads every installed skill's description, so write it for matching.

WeakStrong
Helps with documents.Creates and edits Word (.docx) documents, including tracked changes. Use when the user mentions Word, .docx or editing a document.
Writes content.Writes blog posts in our house format with a quick-answer box and FAQ. Use when asked to draft, write or outline a blog post.

A strong description names the task and the situations that should trigger it. Use the words a real person would type.

5. Write the instructions

Below the settings, write plain Markdown instructions. Keep the body short, because Claude loads it into its working memory whenever the skill triggers.

A reliable structure is:

  • When to use it: one or two sentences.
  • Steps: a numbered list of what to do.
  • Output format: what the result should look like.
  • Rules: what to avoid.
  • Example: one short input and output.

Anthropic's guidance is that the body should stay under about 5,000 tokens. Put anything long into separate files instead.

6. Add extra files only if needed

Claude loads supporting files only when it needs them, so they cost nothing until used.

  • references/ for long documentation, schemas or style guides.
  • scripts/ for code Claude can run, such as a validator.
  • assets/ for templates and other fixed files.

Link to them from SKILL.md, for example "see references/style-guide.md for the full rules".

7. Install it

Where you put the folder depends on where you use Claude.

WhereHow
Claude Code, just for youPlace the folder in ~/.claude/skills/
Claude Code, for a projectPlace it in .claude/skills/ inside the project
Claude.aiZip the folder and upload it in the Skills settings
Claude APIUpload it through the Skills API

Skills do not sync between these places, so install the skill everywhere you need it. More detail is in our guide on how to install an agent skill.

8. Test and improve it

Open a new session and try your test requests. Check three things.

  1. It triggers: Claude uses the skill for a request that should match.
  2. It stays quiet: Claude does not use it for an unrelated request.
  3. It follows the rules: the output matches your format.

If it does not trigger, rewrite the description with the exact words you used. If it triggers too often, make the description narrower.

A template you can copy

Replace the text in brackets, then save it as SKILL.md.

---
name: [skill-name]
description: [What the skill does]. Use when [the situations or phrases that should trigger it].
---

# [Skill name]

## When to use this skill
[One or two sentences describing the task.]

## Steps
1. [First step]
2. [Second step]
3. [Third step]

## Output format
[Describe what the result should look like.]

## Rules
- [Something to always do]
- [Something to never do]

## Example
Input: [a sample request]
Output: [a short sample result]

A finished example

This is a small, complete skill. It shows how specific the description and rules should be.

---
name: blog-post-writer
description: Writes blog posts in our house format with a quick-answer box, short paragraphs and an FAQ. Use when the user asks to draft, write or outline a blog post or article.
---

# Blog post writer

## Steps
1. If the topic, audience or target keyword is missing, ask for it.
2. Open with a one-sentence quick answer.
3. Write paragraphs of one or two sentences.
4. Add a table when comparing three or more options.
5. End with five frequently asked questions.

## Rules
- Never invent statistics. Say when a figure is unverified.
- Keep every paragraph under 200 characters.

Common mistakes

MistakeFix
A vague descriptionSay what it does and when to use it, with real trigger words
One skill for everythingSplit it into several narrow skills
A very long SKILL.mdMove detail into reference files
No test requestsWrite two or three before you start
Forgetting to install it everywhereAdd it to each surface you use

Get help from a skill

You can use skills to write skills. The Writing Skills skill gives Claude a method for creating and testing new skills.

Brainstorming helps you clarify a vague task before you write anything. Anthropic also publishes example skills, including one for creating skills, in its public skills repository.

Before you share it

If you publish your skill, make it easy to trust.

  • Add a licence, such as MIT.
  • Say what the skill does and does not do.
  • Do not include secrets or private data.
  • Explain any scripts, because people will read them before installing.

Our safety checklist shows what reviewers look for, and the SKILL.md guide covers the file format in more depth. For ideas, browse the best Claude Code skills.

Frequently asked questions

How do I create a Claude skill?

Make a folder, add a SKILL.md file with a name, a description and instructions, and install it where Claude looks for skills. Then test it with a realistic request.

Do I need to code to create a skill?

No. Most skills are plain Markdown instructions. Scripts are optional.

How long should a SKILL.md be?

Keep the body short, under about 5,000 tokens. Move long reference material into separate files that Claude loads only when needed.

Why is my skill not triggering?

Usually the description does not match how you phrase your request. Rewrite it to say what the skill does and when to use it, using the words you actually type.

Where do I save a Claude skill?

In Claude Code, use ~/.claude/skills/ or a project's .claude/skills/. In Claude.ai, upload a zip of the folder in the settings.

Methodology and disclosure

This guide draws on Anthropic's published documentation on Agent Skills and its best-practice guidance, checked in November 2026. Product details change often, so confirm against Anthropic's documentation.

We have no affiliation with Anthropic, and this article contains no affiliate links.