How to Create a Claude Skill: SKILL.md Walkthrough (2026)

A Claude skill is a folder with one required file, SKILL.md: a short header that says what the skill does and when to use it, followed by plain-English instructions. To create one in Claude Code, make a folder inside ~/.claude/skills/, write a SKILL.md with a name and a description, then ask for the task in your own words or type / followed by the skill's name. Below you will build a working skill for a marketer, learn how Claude decides when to load it, and install skills other people made.

What a Claude skill is, in plain English

Think of a skill as a saved procedure Claude takes off the shelf when the job calls for it. Instead of pasting the same instructions into every chat, you write them once in a file, and Claude opens them only when your request matches.

Skills use the open Agent Skills format, which Anthropic developed and released as a standard. A skill folder is portable: Claude Code, the Claude apps and the Claude API all accept it, and this guide focuses on Claude Code, where skills are plain files.

Existing users should know that Claude Code merged custom slash commands into skills. An old .claude/commands/review.md file still works, but a skill folder can also hold templates, examples and scripts.

For the first and third cards, see what to put in a CLAUDE.md file and what an MCP server is.

How skills load, and why the description matters most

Anthropic's Agent Skills overview describes a three-level loading system it calls progressive disclosure. A token, in these numbers, is the small chunk of text AI models count, often a short word or part of a longer one.

The first lesson: the description is the trigger. If it doesn't contain the words you naturally use when asking for the task, Claude won't reach for the skill.

The second lesson: every installed skill costs a little attention on every turn, so a few well-used skills beat a long list you forgot about.

Where skills live

The ~ sign means your home folder: /Users/yourname on a Mac and C:\Users\yourname on Windows. If a personal skill and a project skill share a name, the personal one wins.

Build a campaign brief skill, step by step

The example is a skill for a marketer who writes a campaign brief every week. It collects missing inputs first, writes the brief in a fixed structure, and checks its own work before handing it over.

Step 1: Write down the procedure you already follow

Step 2: Create the skill folder

The easiest route is to ask Claude Code to do it:

Create a personal skill folder called campaign-brief in my skills directory (~/.claude/skills/) with an empty SKILL.md file inside it.

If you prefer to type it yourself, use Terminal on a Mac:

$ mkdir -p ~/.claude/skills/campaign-brief
$ 

Or PowerShell on Windows:

PS> New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\campaign-brief"
PS> 

Step 3: Write SKILL.md

Create SKILL.md inside the folder and paste this in. The part between the two --- lines is the frontmatter, a small block of settings written in YAML (a simple "key: value" format), and everything after it is the instructions.

---
name: campaign-brief
description: Writes a one-page marketing campaign brief from rough notes. Use when the user asks for a campaign brief, a creative brief, or a plan for a launch, promotion or email campaign.
---

# Campaign brief

## Before writing
Check that you have these inputs. Ask for anything missing in one short list, then wait:
- Product or offer, and its price if there is one
- Audience: who they are and the problem they have
- Goal: one measurable result, such as demo bookings or first purchases
- Channels and deadline
- Budget, or "none"

## Write the brief
Use exactly these sections, in this order:
1. Summary (three sentences at most)
2. Audience and their main objection
3. Key message and three supporting points
4. Offer and call to action
5. Channels, with one line on the job of each
6. Timeline with dates
7. How we will measure success
8. Open questions

If brand/voice.md exists in this project, read it first and follow it.
Save the brief as briefs/YYYY-MM-DD-campaign-name.md.

## Rules
- Never invent numbers, prices, dates or testimonials. Write [TBD] instead.
- Keep it to one page, about 450 words.
- Use the words the audience would use, not marketing jargon.

## Before you finish
Re-read the brief and confirm that every section is filled or marked [TBD], the goal can be measured, and the call to action matches the offer. List every [TBD] at the end.

Step 4: Add a supporting file

Paste a brief you were proud of into examples.md in the same folder, then add one line under "Write the brief": "For tone and depth, see examples.md." Claude reads the example only when it runs the skill, so it costs nothing the rest of the time.

campaign-brief/
  SKILL.md
  examples.md

Step 5: Test it two ways

Open Claude Code in any project folder. If it was already running and the skills folder is brand new, run /reload-skills first.

First, the automatic test: ask in plain words and watch Claude pick up the skill.

Then the direct test: type /campaign-brief end-of-year sale email, and the text after the skill name is passed along as arguments. To confirm Claude can see the skill at all, ask "What skills are available?" or run /skills.

Step 6: Tune it

Expect a few rounds of edits. Claude Code picks up changes to a skill's files during the session, so edit, save and try again.

• It never triggers: add the words you actually use to the description.
• It triggers when you don't want it: narrow the description, or add disable-model-invocation: true so the skill runs only when you type its command.
• It forgets a rule late in a long session: move that rule near the top. When a long conversation is compacted, Claude Code keeps only the start of each skill it re-attaches.

Optional settings worth knowing

Skip these until your first skill works.

Inside the instructions, $ARGUMENTS marks where the text you type after the command should go.

Use the same skill in the Claude app

Skills work in the Claude web and desktop apps too, with the setup described in Anthropic's help article on using skills:

1. Turn on code execution. On Free, Pro and Max plans, open Settings > Capabilities and enable Code execution and file creation. On Team and Enterprise plans an owner enables it for the organization.
2. Zip the folder. The folder itself must sit at the top of the zip file: campaign-brief.zip contains campaign-brief/SKILL.md.
3. Upload it. Open Customize > Skills, click +, choose Create skill, then Upload a skill.
4. Switch it on and test. Try a few prompts that should trigger it.

The Help Center lists a 200-character limit for the description on claude.ai, one more reason to keep it tight. The example above fits.

Install skills other people made

You don't have to write every skill yourself:

Anthropic's public skills repository also works as a marketplace. These two commands add it and install its example skills, which include brand guidelines, document co-authoring and design skills such as Canvas Design:

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

Claude Code then asks for a scope: just you, everyone on this project, or just you in this project.

Check a skill before you trust it

A skill can tell Claude to run commands and read files, so treat installing one like installing software. Anthropic's docs advise using skills only from sources you trust, meaning ones you wrote or got from Anthropic, and auditing anything else thoroughly.

Troubleshooting

What to do next

Pick one task you have explained to Claude more than twice this month and turn it into a skill today, using the campaign brief as your template. Test it with three different phrasings before you rely on it.

For ideas worth packaging, the workflows in Claude Code for marketers translate well into skills, and the Claude Skills directory shows what others have built. If you want a guided setup of skills, MCP and CLAUDE.md together, the Claude Code course covers all three in its setup module.