Writing and sharing your own skill for Claude

A skill turns the instructions you keep pasting into a file Claude loads itself. Where you put the folder decides who uses it: just you, your team or everyone.

Anyone who uses Claude for a while ends up pasting the same instructions into the conversation. How we write release notes. What we check when reviewing a pull request. Which words are not allowed in our copy. Every new session starts with the same block of text, and the one time someone forgets it, the output is slightly off.

A skill turns that block into a file Claude loads by itself when the task comes up. You write the instructions once, Claude recognises when they apply, and your colleagues work from the same version instead of each keeping their own copy in a notes file.

What a skill actually is

A skill is a folder containing a file called SKILL.md. At the top of that file sits a short YAML header, followed by the instructions in Markdown. Alongside SKILL.md, the folder can hold extra reference files or scripts, such as an example of a good piece of text or a script that fetches data.

release-notes/
├── SKILL.md
└── style.md

How Claude loads a skill determines how you should write it. At startup, Claude sees only the name and description of each skill. It reads the body of SKILL.md only when the skill is needed, and extra files only when SKILL.md points to them. Scripts are run rather than read, so they cost no context.

It follows that the description is where you should spend most of your time. Claude holds the task up against those few lines and decides from them whether to open the rest. A vague description gives you a skill that never gets loaded, however good the instructions underneath it are.

The description is the only part of your skill that Claude always reads. Everything else depends on it.

A skill for release notes

As an example, we will take a skill called release-notes. It turns the git commits since the last release into release notes for customers: not commit messages like 'fix typo in handler', but sentences a user understands and can act on. A few fixed rules apply to the header and the body.

name: lowercase letters, digits and hyphens, 64 characters at most
description: 1024 characters at most, covering what the skill does and when to use it
the main use case first in the description
body: a short numbered procedure, not an essay
SKILL.md under roughly 500 lines

---
name: release-notes
description: Writes customer-facing release notes from the git commits since the last tag. Use when asked for release notes, a changelog entry, or what changed since the last release.
---

# Release notes

1. Find the last release tag: `git describe --tags --abbrev=0`
2. List the commits since then: `git log <tag>..HEAD --oneline --no-merges`
3. Group the changes under New, Improved and Fixed. Skip refactors, tests and dependency updates.
4. Write one plain sentence per change, for a customer rather than a developer. No commit hashes.
5. Follow the tone and examples in [style.md](style.md).

The description opens with the most common case: drafting release notes for a new version. Other triggers, such as updating a changelog, come after that. The body itself is a sequence of steps Claude works through: find the last release, collect the commits since then, drop internal changes, then group the rest and rewrite it in customer language. A procedure leaves less room for interpretation than an explanation of what good release notes look like.

Detail that is not needed on every run belongs in a separate file, such as a style guide for customer-facing copy or a list of official product names. SKILL.md refers to these and says each time what the file contains, so Claude knows when it is worth opening. That keeps the skill light in the cases where the detail is not needed.

In Claude Code, you do not have to wait for Claude to pick up the skill on its own. Type /release-notes and the skill is invoked directly. That is handy while testing, and for tasks you know in advance will need this skill.

Where to put the skill

Where the folder lives decides who can use the skill. There are four options, and they differ in more than the path: also in how changes reach other people and what happens when two skills share a name.

Just for yourself, in Claude Code

Put the folder in ~/.claude/skills/ in your home directory. The skill then works across all your projects, but only on your own machine. This is the place for personal working habits, and for a skill you want to try out yourself before sharing it.

Shared with your team, in Claude Code

Put the folder in .claude/skills/ inside the project repository and commit it. Everyone working in that repository gets the skill, and changes go through the same review and version history as code. Anyone changing the release-notes skill therefore does so in a pull request a colleague can block. Watch the names, though: if a personal skill and a project skill share a name, the personal one wins, and you end up seeing something different from the rest of the team.

Public or across many repositories

If you want to use a skill in many repositories or share it publicly, package it as a plugin and publish it in a plugin marketplace. Such a marketplace is simply a git repository. Others add it with /plugin marketplace add followed by the repository, then install with /plugin install. Skills from a plugin get the plugin name as a namespace, so your release-notes never clashes with someone else's.

In the Claude apps

On claude.ai, you zip the folder and upload it via Settings, Features. Uploaded skills are personal: each colleague uploads their own copy, and they do not sync with Claude Code. Any change has to be passed round to everyone by hand. The apps also accept only a handful of header fields, including name and description, so a skill that has to work in both environments is best kept to those two.

Checking that a skill works

The format follows an open standard, Agent Skills. Anthropic also offers a skill-creator plugin that helps with writing, testing and refining a skill. It takes some of the initial work off your hands, but whether your skill improves the output is still something you have to check yourself.

To do that, run the same task in a fresh session, once with the skill and once without, and compare the results side by side. Claude picking up the skill proves only that it found it, not that it helped. If the version with the skill produces the same release notes as the one without, the skill is not adding anything yet, and that is where the next round starts.