Skip to main content
Claude skill

Claude Skill Template (SKILL.md)

An annotated SKILL.md to fill in, plus a reference file that shows how to keep the main file short.

By Matthews WongUpdated Checked against Claude Code 2.1.323 docs

Key takeaway

A skill folder you rename and fill in. The frontmatter shows a description written the way that triggers: what the skill does, then when to use it, in the words a real request contains. The body gives you the sections a working skill needs, and reference.md shows where long detail goes so SKILL.md stays short.

2 files

The files

Exactly what the download contains. Read it first, then copy or download.

my-skill/SKILL.md2.1 KB
my-skill/SKILL.md
---
name: my-skill
description: Writes release notes from merged pull requests in the house format. Use when the user asks for release notes, a changelog entry, "what changed in this release", or names a version tag to summarize.
---

<!--
HOW TO FILL THIS IN (delete this comment when you are done)

1. Rename the folder and the `name` above to the same lowercase-hyphen name.
   The name is what you type after the slash, as in /my-skill.
2. Rewrite `description`. It is the only part Claude sees before the skill
   is used, so it decides whether the skill triggers. Pattern:
   sentence 1 = what the skill does,
   sentence 2 = "Use when ..." with the words a real request contains.
   Put the main use case first. Avoid a colon followed by a space inside
   the value, or wrap the whole value in quotes, so the YAML stays valid.
3. Replace every [bracketed] part below. Delete sections you do not need.
4. Keep this file short. Move long detail to reference.md and link to it.
-->

# [Skill title]

[One or two sentences: the job this skill does and the result it produces.]

## When to use

- [A request that should trigger it, in the words a person would use]
- [A second request, phrased differently]
- Not for: [a nearby task this skill should leave alone]

## Steps

Follow these in order for the whole task.

1. [Gather what you need first: which files to read, which command to run]
2. [Do the main work. One action per step]
3. [Check the result: the command or test that proves it]
4. [Report, using the format under "What to report"]

## Rules

- [A rule that must hold every time, written as a plain instruction]
- [A thing never to do, with the reason in a few words]
- If [something required] is missing, stop and ask. Do not guess.

## Examples

Input: [a short, realistic request]

Output:

```text
[The exact shape of a good result. Short is fine.]
```

## What to report

- [What was done, in one line]
- [What was checked, and the real output of that check]
- [Anything left undone or uncertain]

## Additional resources

- For [the detailed format, field list or edge cases], see
  [reference.md](reference.md). Read it only when the task needs that detail.
my-skill/reference.md821 B
my-skill/reference.md
# [Skill title]: reference

This file is not loaded with the skill. Claude opens it only when SKILL.md
points here and the task needs the detail. Put anything long or rarely needed
in a file like this one, so the main file stays short.

Good candidates for a reference file:

- A full format or field list
- Edge cases and how to handle each one
- A long set of examples
- A lookup table

## [Format or field list]

| Field     | Required | Notes                             |
| --------- | -------- | --------------------------------- |
| [field-1] | yes      | [what goes here, with an example] |
| [field-2] | no       | [when to include it]              |

## Edge cases

- [Situation]: [what to do]
- [Situation]: [what to do]

## More examples

Input: [a harder request]

Output:

```text
[The expected result]
```
How to use it

From download to working

Use it when

  • You keep pasting the same procedure into Claude and want it to load on its own.
  • You wrote a skill and Claude never uses it, so you need a description pattern that matches requests.
  • Your team wants every skill in the repository to follow one structure.
  • Your CLAUDE.md has grown a long checklist that only matters for one kind of task.
  1. Unzip into your skills folder

    The archive holds one folder, my-skill. Unzip it into .claude/skills/ in your project so the file sits at .claude/skills/my-skill/SKILL.md, or into ~/.claude/skills/ to have it in every project on your machine.

  2. Rename the folder and the name

    Give the folder and the name field the same lowercase name with hyphens, such as release-notes. That name is the command you type after the slash.

  3. Rewrite the description first

    Keep the pattern: one sentence on what the skill does, then Use when with the phrases people really type. Claude decides from this text alone whether to load the skill, so put the main use case first.

  4. Fill the body and delete the comment

    Replace each bracketed part, remove sections you do not need, and delete the how-to comment at the top. Move anything long into reference.md and keep the link to it.

  5. Check that it is listed, then try it

    In Claude Code, ask What skills are available? or open /skills and look for your skill. If the skills folder did not exist when the session started, run /reload-skills. Then type the slash command, and also try a plain request that should trigger it.

What is inside

Why it is written this way

A description that says what and when

The docs describe the field as what the skill does and when to use it, and Claude uses it to decide when to apply the skill. The template's description is a worked example of that pattern, with trigger phrases in the second sentence.

Only two frontmatter fields

name and description are both part of the Agent Skills format, so the same file is valid outside Claude Code too. Claude Code accepts more fields, such as disable-model-invocation and allowed-tools; add them only when you need them.

A body in the order Claude works

When to use, numbered steps, rules, one example and what to report. The most important instructions sit near the top, because after a long conversation is compacted Claude Code may keep only the start of an invoked skill.

A second file that loads only when needed

SKILL.md links to reference.md and says what is in it. Claude opens that file only when the task calls for the detail, so a long format or a table of edge cases adds nothing to the context until then.

Watch for

What goes wrong

  • A vague description such as Helps with releases gives Claude nothing to match. Name the task and the words a request would contain.
  • If the frontmatter YAML is malformed, the skill still runs by its slash command but Claude cannot match the description. A colon followed by a space inside an unquoted description is the usual cause.
  • A skill is guidance, not enforcement. A rule that must hold on every edit belongs in a hook.
  • Every description sits in context all the time and long ones get cut off in the listing. Keep it to the point and keep SKILL.md under 500 lines.
Questions

Frequently asked

Short answers before you download it.

Where do I put a Claude skill?

A project skill lives at .claude/skills/<skill-name>/SKILL.md inside the repository and loads in sessions in that repository; commit it so your team gets it too. A personal skill lives at ~/.claude/skills/<skill-name>/SKILL.md and loads in every project on your machine.

Which frontmatter fields does SKILL.md need?

In Claude Code every field is optional, and only description is recommended, because Claude uses it to decide when to apply the skill. name defaults to the folder name. This template sets both so the file reads the same wherever you put it.

How does Claude decide to use a skill?

Claude Code keeps a listing of skill names and descriptions in context and loads a skill's full content when a request matches its description. You can also invoke it yourself by typing a slash and the skill name. The body is not read until one of those happens.

Do I need to restart Claude Code after adding a skill?

Usually not. Claude Code watches the project and personal skills folders and picks up an added or edited skill within the current session. If the skills folder itself did not exist when the session started, run /reload-skills.

How long can a skill description be?

The docs say the description text is truncated at 1,536 characters in the skill listing, and with many skills installed some descriptions are dropped to fit a budget. Put the main use case first so it survives, and keep the rest short.

Go deeper

Learn what this file packages

Free lessons and articles on this site that explain the ideas behind it.

Sources

Primary sources checked on the research date. Follow them for the current version.

More from the toolkit

Take these too

Claude skillFree

Commit Message Skill for Claude Code

Reads the staged diff and writes a commit message that says what changed and why. It never commits for you.

  • Claude Code
  • Git

2 files5.7 KB.zip

Claude skillFree

Pull Request Description Skill for Claude Code

Reads the branch diff and fills a PR template: why, what changed, real test results, risks and rollback.

  • Claude Code
  • Git

2 files5.8 KB.zip

TemplateFree

CLAUDE.md Template for Any Repository

A 70-line starter CLAUDE.md: project, stack, commands, hard rules, how to verify work and what not to do.

  • Claude Code

1 file2.1 KB.md

All toolkit items