How to create a Claude skill (with a working example)

A Claude skill is a folder with one file, SKILL.md, that tells Claude how to do a specific job and when to do it. To create one, you write a short description of when to use it, the steps Claude should follow and what the finished output looks like. Then you add the folder to Claude Code, or zip it and upload it in the Claude app.

What is a Claude skill, exactly?

A Claude skill is a reusable set of instructions, plus optional reference files and scripts, that Claude loads only when a task needs it.

Anthropic's Agent Skills documentation describes three layers. The name and description are always loaded, at roughly 100 tokens per skill. The body of SKILL.md loads when the skill is triggered. Extra files load only when the instructions point to them.

That design is why I like skills for business work. You can install fifteen of them and Claude only reads the one that fits the conversation. The rest sit there costing almost nothing, and the one you need runs the same method every time. You stop pasting the same prompt into every new chat.

I build skills for my own businesses and sell a set of them as agents in The Stack. So everything below comes from writing skills that have to produce a document someone can use the next morning.

What goes inside a skill folder?

At minimum, a folder with the skill's name and a SKILL.md file inside it. Everything else is optional, and I'd leave it out until the skill actually needs it.

Here's the folder for a simple skill that writes an offer one-liner:

offer-one-liner/
├── SKILL.md
└── references/
    └── examples.md

How do you write the SKILL.md file?

SKILL.md starts with YAML frontmatter between two lines of three dashes, then the instructions in plain Markdown. Here's a complete, working example. Copy it and make it yours:

---
name: offer-one-liner
description: Writes a one-sentence description of a consulting or fractional offer, plus three variants to test. Use when someone asks for a one-liner, elevator pitch or LinkedIn headline.
---

# Offer one-liner

## Before you write
Ask for anything missing, one question at a time:
1. Who buys this? A role and a type of company.
2. What happens that makes them look for help?
3. What result do they get, in their own words?
4. What proof exists? A number, a past role or a client result.

## Write
- One sentence, under 25 words: who + problem + result + proof.
- Use words the buyer would say out loud.
- Then write three variants: one leading with the result,
  one with the problem and one with the proof.

## Check before answering
- Could a competitor say the same sentence? If so, make the proof more specific.
- Would the buyer recognise themselves in the first five words?

## Output
The one-liner, the three variants, and one sentence on
which variant to test first and why.

The rules for the frontmatter

• name: lowercase letters, numbers and hyphens, up to 64 characters. Anthropic's docs also reserve the words "claude" and "anthropic", so keep them out of the name.
• description: what the skill does and when to use it. The developer docs allow up to 1,024 characters, but the Claude help center gives a 200-character limit for skills uploaded to the Claude app. My rule: stay under 200, and one file works everywhere.

In Claude Code, the frontmatter can also decide who gets to start the skill. According to the Claude Code skills docs, disable-model-invocation: true means only you can run it with /skill-name. I'd use that for anything you don't want Claude kicking off on its own.

How do you write a description Claude will actually use?

Write it as a trigger list: one clause on what the skill produces, then the phrases a person would type when they need it.

Claude compares your request with the description of every installed skill and loads the one that matches. So a vague description like "helps with marketing" either never fires or fires for everything. Here's what that looks like side by side:

Both strong versions fit in 200 characters, name the output and list the words people use. I'd spend most of your effort on that last part. People rarely type "value metric". They type "what should I charge", so that's the phrase your description needs.

What makes a business skill better than a prompt?

A business skill earns its place when it forces a method you'd otherwise skip. Four things make the difference, and I wouldn't ship a skill without all of them:

1. It asks before it writes. List the inputs the skill needs and tell Claude to ask for the missing ones, one at a time. Most weak output comes from Claude guessing who the customer is or what the price should be.
2. It names the method. Point to a specific framework, such as April Dunford's positioning steps or Blair Enns's three pricing options, and describe how to apply it. Ask for "good positioning" and you'll get average positioning.
3. It has a quality bar. Add a short checklist Claude runs before answering, like the competitor test in the example above. This is where most of the quality comes from.
4. It ends with a template. Define the exact sections of the output. When a skill produces the same document every time, you can build a process on top of it.

Once you have more than one skill, add a fifth thing: a shared context file. In The Stack, a setup skill writes the business model, stage and price band to one file, and every other skill reads it. Nobody answers the same questions fifteen times.

It also lets each skill load a different reference file for services, software or product businesses, so SKILL.md stays short instead of carrying every variant.

How do you install and test your skill?

Install it where you work. Then test that it triggers at the right moments before you trust it with anything real.

In Claude Code

1. Save the folder to ~/.claude/skills/offer-one-liner/ to use it in every project, or to .claude/skills/offer-one-liner/ inside a repository to share it with whoever works there.
2. Start a session and ask for something that should trigger it, or run it directly with /offer-one-liner.

In the Claude app

1. Turn on code execution in Settings. Skills need it.
2. Zip the folder so the skill folder itself sits at the root of the zip, with SKILL.md inside it. A zip with SKILL.md loose at the root is the most common upload mistake.
3. Upload it under Customize > Skills and switch it on. Menu names change, so check the help center if you can't find it.

Skills don't sync between Claude Code, the Claude app and the API. Install the skill separately in each place you use it.

Testing it

Don't skip this part. A skill that never fires is just a file you forgot you wrote.

• Write five requests that should trigger the skill, phrased the way a real person would ask, and two that shouldn't.
• Run them in fresh conversations. If the skill doesn't fire, add the missing phrases to the description. If it fires too often, narrow it.
• Check the output against your quality bar. When it fails the same way twice, add a line to the checklist. Running it again and hoping won't fix it.

What are the most common mistakes?

These are the four I'd check first when a skill misbehaves.

• A description that says what, but not when. Claude can't match "A positioning framework" to "nobody understands what we do".
• One giant skill. A skill that does positioning, pricing and a launch plan triggers at odd moments and gives you a long, shallow answer. Split it by output: one skill, one document.
• No questions step. Without it, Claude fills the gaps with plausible guesses, and the document looks finished when it isn't.
• Installing skills you haven't read. Anthropic's docs warn that a skill can direct Claude to run tools or code. Only install skills you wrote or trust, and read every file first. Mine included.

Questions people ask