How to Create Claude Code Skills (With a Working Example)

To create a Claude Code skill, make a folder in .claude/skills/ (for one project) or ~/.claude/skills/ (for all your projects), add a SKILL.md file with a description in the frontmatter and your instructions below it, then run it with /skill-name or let Claude load it when a request matches.

This tutorial covers what skills are, where they live, the frontmatter fields, how Claude decides to load them and a complete example for agency work. Checked against Claude Code's skills docs, October 2026.

What a skill is

A skill is a reusable set of instructions, and optionally scripts and reference files, that Claude Code can load when it needs them. Think of it as a written procedure for a task you do repeatedly: writing a weekly client report, deploying to staging, reviewing a pull request against your checklist.

Skills differ from CLAUDE.md in when they load. CLAUDE.md is read at the start of every session. A skill's full instructions load only when the skill is used, so you can have many skills without filling Claude's context with all of them at once.

Where skills live

Location	Path	Use it for
Personal	~/.claude/skills/<skill-name>/SKILL.md	Your own skills, in every project on your machine
Project	.claude/skills/<skill-name>/SKILL.md	Skills for one repo. Commit them to share with your team
Plugin	<plugin>/skills/<skill-name>/SKILL.md	Skills you distribute as part of a plugin

There are also enterprise and nested locations. If two skills share a name, enterprise overrides personal, and personal overrides project. The folder name becomes the command name unless you set name in the frontmatter.

The SKILL.md format

A skill file is markdown with YAML frontmatter at the very top:

---
name: my-skill
description: What this skill does and when to use it.
---

Instructions Claude follows when the skill runs.

Every frontmatter field is optional, but description is the one that matters most, because Claude uses it to decide when to load the skill. Useful fields:

Field	What it does
name	The command name. Defaults to the folder name
description	What the skill does and when to use it
when_to_use	Extra trigger context, added to the description
argument-hint	Autocomplete hint, such as [client-name]
disable-model-invocation	true means only you can run it, with /name
user-invocable	false hides it from the / menu so only Claude uses it
allowed-tools	Tools Claude can use without asking while the skill runs
paths	File patterns that limit when it activates automatically

Field names must match exactly. Unrecognized fields are silently ignored, so a typo won't show an error.

How Claude decides to load a skill

In a normal session, Claude sees the descriptions of all available skills. When your request matches a description, Claude loads that skill's full SKILL.md. Supporting files load only when the instructions point to them and Claude needs them.

That means the description does the work. Write it the way you'd describe the task to a colleague, and include the words you'd actually type:

• Weak: description: Reports
• Better: description: Write the weekly client report from this week's run logs. Use when asked for a weekly report, client update or Friday summary.

You can always run a skill directly by typing /skill-name, with arguments after it, such as /weekly-client-report acme. Inside the skill, $ARGUMENTS receives whatever you typed after the name.

A complete example: a weekly client report skill

Say you run automations for several clients and send each one a weekly summary. Each client folder has a logs/ folder of run logs and a reports/ folder.

Create the folder and file:

.claude/skills/weekly-client-report/
├── SKILL.md
└── template.md

SKILL.md:

---
name: weekly-client-report
description: Write the weekly report for an automation client from this week's run logs. Use when asked for a weekly report, client update or Friday summary.
argument-hint: [client-folder]
---

Write this week's report for the client in `clients/$ARGUMENTS/`.

1. Read every log file in `clients/$ARGUMENTS/logs/` dated in the last 7 days.
2. Count: total runs, successful runs, failed runs, and items handled
   (leads answered, emails triaged or appointments booked, whichever
   the logs record).
3. List each failure with its date and the error message. Group repeats.
4. Fill in [template.md](template.md) with those numbers. Keep it under
   250 words and use plain language a business owner understands.
5. Save it as `clients/$ARGUMENTS/reports/<today's date>.md`.
6. Show me the report. Don't send anything.

If the logs folder is missing or empty, stop and tell me.

template.md:

# Weekly update: [Client name], [date range]

**This week:** [one sentence on what the automation did]

| | This week |
|---|---|
| Runs | [n] |
| Successful | [n] |
| [Items handled] | [n] |

**Issues:** [none, or a short list with what was done about each]

**Next week:** [one planned change or "no changes planned"]

Run it with /weekly-client-report acme, or just ask "write this week's report for acme" and Claude should load it from the description.

Supporting files

Keep SKILL.md focused. The docs recommend keeping it under 500 lines and moving detailed material into separate files in the skill folder, such as a reference.md, examples.md or a scripts/ folder. Link them from SKILL.md so Claude knows when to open them. Scripts in the folder can be run rather than read, which is useful for anything that should be exact every time, like a formatting or validation step.

Testing your skill

1. Run it directly with /skill-name and check the output.
2. Test automatic loading. Start a fresh session and phrase the request a few different ways. If Claude doesn't pick it up, make the description more specific and include the phrases you use.
3. Test edge cases. Missing files, empty logs, a client folder that doesn't exist. Add instructions for each.
4. Check it doesn't over-trigger. If it loads when you didn't want it, narrow the description, add paths, or set disable-model-invocation: true so it only runs when you call it.

Sharing skills

• With a team: commit .claude/skills/ to the repo. Everyone who clones it gets the skills.
• Across projects: put it in ~/.claude/skills/ on your machine.
• As a package: add a skills/ folder to a Claude Code plugin, so others can install your set of skills together.

Learn to build with Claude Code

The Stride AI Coding course teaches Claude Code and Codex for building custom tools for clients, written for non-programmers, with weekly live calls. The free guide library includes walkthroughs of specific Claude Code skills.

FAQ

Can Claude Code create its own skills?

Yes. You can ask Claude Code to write a skill for a task you've just done together, then review the SKILL.md it creates before saving it. Check the description carefully, since that controls when the skill loads.

How do I get skills into Claude Code?

Create a folder with a SKILL.md file in ~/.claude/skills/ or your project's .claude/skills/, or install a plugin that includes skills. Claude Code picks them up from those locations.

What's the difference between a skill and CLAUDE.md?

CLAUDE.md holds instructions Claude reads at the start of every session, like project conventions. A skill holds instructions for a specific task and loads only when that task comes up or when you run it with /skill-name.

Can you run a skill manually?

Yes. Type / followed by the skill's name, with any arguments after it. If you want a skill to run only when you call it, set disable-model-invocation: true in its frontmatter.