THE CLAUDESKILLS HUB
Write your first skill

Write your first Claude skill, from empty folder to installed

A skill is a folder with a SKILL.md file in it. This guide builds one real skill end to end, and stops at each point where a decision is easy to get wrong. It assumes nothing except that you have a workflow you have already done by hand more than once.

The seven steps

  1. 1. Start from a workflow you have already repeated

    Do not start from an idea. Start from something you have done by hand at least three times, because that is the only way you know which steps are real and which ones you imagined. If you cannot describe the job without saying it depends, it is too early to encode it.

  2. 2. Create the folder, and name it exactly

    The folder name and the name field must match, and the name is constrained: lowercase letters, numbers and hyphens only, no leading or trailing hyphen, no double hyphen, 64 characters at most. Renaming later means renaming both, so pick a name you can live with.

    my-skill/
├── SKILL.md          # required
├── references/
│   └── REFERENCE.md  # loaded only when needed
└── scripts/
    └── check.py
    Only SKILL.md is required. Everything else is loaded on demand.

  3. 3. Write the description before the body

    The description decides whether your skill is ever loaded, so write it first, while you still remember the task in the words a person would use. Say what the skill does and when to use it, and include the phrasings a colleague would reach for rather than the ones you would.

  4. 4. Write the body as a procedure, not an essay

    The body is read only after the agent has decided to activate the skill, so it should contain steps, decision points and the shape of the output. Leave out general knowledge the model already has: it costs context and adds nothing.

    ---
name: release-notes
description: Writes release notes from merged pull requests, grouped by user facing change. Use when preparing a release, writing a changelog, or when the user mentions release notes.
---

# Release notes

## Steps
1. List merged pull requests since the previous tag.
2. Group them by user facing change, not by author or by file.
3. Drop internal refactors unless they change behaviour.
4. Write one line per change, in the present tense.

## Output
A Markdown list under a version heading. No emoji. No marketing language.
    A complete, valid skill. The output section is what stops the format drifting.

  5. 5. Add optional fields only when they earn their place

    Most skills need nothing beyond name and description. Add license when you publish, compatibility only when the environment genuinely matters, and metadata for anything the spec does not define. allowed-tools is experimental, so treat support for it as uncertain.

    ---
name: release-notes
description: Writes release notes from merged pull requests, grouped by user facing change. Use when preparing a release, writing a changelog, or when the user mentions release notes.
license: MIT
compatibility: Requires git and network access to the repository host
metadata:
  author: example-org
  version: "1.2"
---

  6. 6. Split anything long into references

    The body loads in full every time the skill activates, so keep it under roughly 500 lines and move detail into references/. Keep those references one level deep, because a chain of files that point at each other is slower and easier to get lost in.

    See [the full grouping rules](references/GROUPING.md).

Run the collector first:
scripts/collect.py --since v1.4.0

  7. 7. Validate, then test the trigger with someone else's words

    Run the validator first, since naming and frontmatter errors show up as a skill that silently never loads. Then test the part no validator can check: ask for the task the way a colleague would phrase it, and see whether the skill activates. If it does not, the description is wrong, not the body.

    skills-ref validate ./my-skill

The five mistakes that cost the most

Every one of these produces a skill that looks fine in review and fails in use, which is why they survive so long.

A description written in your own vocabulary
It matches your phrasing and nobody else's. This is the single most common reason a good skill is never used.
An essay instead of a procedure
Background and rationale burn context every time the skill activates without changing what the agent does.
Encoding knowledge the model already has
Explaining what a pull request is adds tokens and no behaviour. Encode your conventions, not the domain.
Two skills that instruct the same decision
The agent gets contradictory instructions and resolves them invisibly. Keep one source of truth per job.
Never testing the trigger
Everyone tests the body by activating the skill manually. Almost nobody tests whether it activates on its own.

Distributing it

A skill is a folder, so distribution is just publishing that folder somewhere installable, most simply a public repository that people add with the skills CLI. Before you publish, read the compatibility map: if your skill instructs the agent on a decision another popular skill already owns, say so in your own description rather than leaving users to discover the conflict.

npx skills add owner/repo

SKILL.md referenceDescription checkerConflicts and pairings