← Back to Lessons
Claude Skills

Build Your Own Skill

Once you have used a few skills, building one is the natural next step. A skill is just a folder and a SKILL.md file. Here is how to make one Claude actually uses.
⏱ ~15 min

The capstone. You have seen skills in action. Now you build one. The good news: a skill is one of the simplest things you can create. A folder, a single Markdown file, done.

The catch worth getting right. The hard part is not the structure. It is writing a description that makes Claude reach for your skill at the right moments and leave it alone the rest of the time. That is what most of this lesson is about.

1
The shape of a skill
2 min

At minimum, a skill is a folder containing one file named SKILL.md:

~/.claude/skills/your-skill-name/SKILL.md

That SKILL.md has exactly two parts:

Part 1: Frontmatter

A short block at the very top, fenced by --- lines, with two required fields: name and description. This is the only part Claude sees until your skill triggers, so it has to do the work of getting noticed.

Part 2: Instructions

Everything below the frontmatter. Plain Markdown telling Claude how to do the job. This loads only when the skill actually fires, so length here is cheap.

A skill can grow beyond this: a scripts/ folder for code Claude runs, a references/ folder for docs it reads only when needed, an assets/ folder for templates. But you start with just the one file.

2
Write the description like it is your one shot
3 min

This is the whole game. Claude decides whether to use your skill by reading the description and nothing else. A vague description means your skill sits unused. So:

  • Say what it does AND when to use it. Both. The "when" is what makes it trigger.
  • Be a little pushy. Claude tends to under-trigger skills, meaning it skips them even when they would help. Counter that by naming the situations explicitly: "Use this whenever the user mentions X, Y, or Z, even if they do not say the word 'skill'."
  • Name real phrasings. Think about what a user actually types. Put those words in the description.

Weak description

"Builds a dashboard."

Too thin. Claude has no idea when this is the right tool.

Strong description

"How to build a simple fast dashboard to display internal data. Use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they do not explicitly ask for a 'dashboard.'"

It says what it does and lists the moments it should fire.

3
Keep the instructions tight
2 min

Below the frontmatter, write the actual steps. A few principles keep skills sharp:

  • Use the imperative. "Read the file, then summarize it." Direct instructions, not descriptions of what might happen.
  • Explain the why, not just the what. Claude is smart. When you tell it why a step matters, it handles edge cases you did not spell out. Heavy-handed rules in all caps tend to backfire.
  • Stay lean. Aim to keep SKILL.md reasonably short. If it is getting long, move the detailed reference material into a separate file and point to it: "For the full format options, read references/formats.md." Claude loads that only when it needs it.
  • Show an example or two. A sample input and the output you want is worth more than a paragraph of explanation.

The goal is a skill that a smart teammate could follow without you standing over their shoulder.

4
Let Claude build it with you
2 min

You do not have to hand-write any of this. There is a skill for making skills, called skill-creator, and it walks you through the whole process: capturing what you want, drafting the SKILL.md, and tightening the description so it triggers reliably.

Just ask:

I want to create a skill that takes a messy meeting transcript and turns it into a clean summary with action items. Help me build it from scratch.

Claude will ask what the skill should do, when it should trigger, and what the output should look like, then write the folder and the SKILL.md for you. You review and adjust.

You are the editor

Even when Claude drafts it, read the description with fresh eyes. Does it name the situations where you would actually want this? That is the part only you can judge.

5
Install and iterate
2 min

Once the file exists at ~/.claude/skills/your-skill-name/SKILL.md, restart Claude Code so it picks up the new skill. Then test it the honest way: open a fresh session and type the kind of request a real user would, without naming the skill. Does it fire on its own?

  • It fired and did the job. You are done. Use it.
  • It did the job but missed something. Edit the instructions. Add the step it skipped, or explain why that step matters.
  • It did not fire at all. The problem is almost always the description. Add the phrasings you actually used. Make it more specific about when to trigger.
Restart to reload

Claude detects skills when a session starts. After every edit to SKILL.md, start a new session before you test again, or you will be testing the old version.

Iterating is normal. The first draft rarely triggers perfectly. Tweak the description, retest, repeat. That loop is the entire craft.

6
You have finished the course

That is the whole Claude Skills track. You now know what a skill is, how to install and use several real ones, and how to build your own from scratch. Everything else is just more skills.

If you have not yet, go back and try the building blocks hands-on:

Questions?

Made by AI Service Engine · what is a skill? · the YouTube Transcript skill