Installing a skill someone else built takes one command. Writing your own takes about ten minutes once you know the format — this is the format, plus a real example built from scratch.
If you have not installed a skill before, start with what a Claude Skill actually is first — this guide assumes you already know the basic shape.
The SKILL.md format
Every skill is one file: SKILL.md. It has two parts.
A YAML frontmatter block, with exactly two required fields:
---
name: reviewing-contracts
description: Reviews a contract for risk before signing or negotiation, flagging unusual clauses, missing standard protections, and terms that favour the other party. Use when a contract, NDA, or agreement needs review before it is signed.
---
name— lowercase letters, numbers, and hyphens only, up to 64 characters. This becomes part of the skill's identity and, inside a plugin, part of how it is invoked.description— up to 1024 characters, written in the third person. This is the single most important line in the whole file — see below.
The instructions, in plain Markdown, below the frontmatter:
# Reviewing Contracts
When reviewing a contract:
1. Read the full document before flagging anything
2. Identify the contract type and which party you represent
3. Flag clauses that are unusual for this contract type
4. Flag standard protections that are missing
5. Note anything that creates asymmetric risk
Output format: a short summary paragraph, followed by a
clause-by-clause table with columns for Clause, Risk Level,
and Recommendation.
That is the entire file. No code, no configuration beyond the two frontmatter fields.
Writing a description that actually triggers
This is the part almost everyone gets wrong on the first try, because a skill is only as good as its ability to fire at the right moment.
Claude does not read your instructions to decide whether a skill applies — it reads the description. If the description is vague ("Helps with contracts"), Claude has nothing to match against and the skill sits installed but silent. A description that works states two things explicitly: what the skill does, and when to use it, in words a person would actually say.
✗ Weak: Helps with contracts.
✓ Strong: Reviews a contract for risk before signing or negotiation,
flagging unusual clauses and missing protections. Use when
a contract, NDA, or agreement needs review before signing.
The second version works because "review this contract," "check this NDA before I sign," and "is this agreement standard" all map onto it naturally. Write the description the way you would explain the skill out loud to a colleague, not as a formal spec.
A worked example, start to finish
Say you write the same style of commit message constantly and want Claude to match it without being told every time.
Step 1 — create the folder:
mkdir -p .claude/skills/writing-commit-messages
Step 2 — write SKILL.md:
---
name: writing-commit-messages
description: Writes git commit messages in imperative mood with a short summary line under 50 characters, followed by a blank line and a body explaining why the change was made. Use when committing code changes or asked to write a commit message.
---
# Writing Commit Messages
Write commit messages in this format:
1. Summary line: imperative mood ("Add", "Fix", "Remove" —
not "Added" or "Adding"), under 50 characters, no period
2. Blank line
3. Body: explain *why* the change was made, not what changed
(the diff already shows what changed)
4. Wrap body lines at 72 characters
Do not include phrases like "this commit" or "this change" —
start directly with the action.
Step 3 — test it:
claude --plugin-dir ./.claude/skills/writing-commit-messages
Make a change, ask Claude to commit it, and check the message follows the format. Edit the file and run /reload-plugins to pick up changes without restarting.
That's a complete, working skill.
Adding supporting files
A skill folder can hold more than SKILL.md. Reference templates, example outputs, or scripts from within your instructions, and Claude loads them only when actually needed — keeping the skill cheap to have installed even if it is rarely used:
writing-commit-messages/
SKILL.md
examples/
good-commit.txt
Standalone skill vs. plugin
A single skill in .claude/skills/ is enough for personal use, and is invoked with a short name like /writing-commit-messages.
Wrap it in a plugin once you want to share it — with a team, across your own projects, or through a marketplace. A plugin needs a manifest:
// .claude-plugin/plugin.json
{
"name": "my-commit-skills",
"description": "Commit message formatting skills",
"version": "1.0.0",
"author": { "name": "Your Name" }
}
with the skill moved into skills/writing-commit-messages/SKILL.md inside that plugin folder. Plugin skills are namespaced (/my-commit-skills:writing-commit-messages) so they never collide with someone else's plugin using the same skill name.
Sharing what you built
Once a skill works, there are two ways to get it into other people's hands, matching the two ways skills get installed:
- A marketplace, for Claude Code users — see how the Claude Skills Marketplace works for a full worked example using a real, live marketplace.
- A zip file, for claude.ai and Cowork users, with the skill folder at the zip's root (
skill-name/SKILL.md) — uploaded via Customize → Skills → Add.
Related Resources
- What Are Claude Skills? The Complete Beginner's Guide — start here if you have not installed one yet
- Claude Skills Marketplace — how to add and install — distributing what you build
- Claude Skills Examples by Profession — 40 real descriptions to study the pattern from
- Browse Claude Skills by profession — see complete, real SKILL.md files