How to build a Claude skill: SKILL.md from scratch

A skill is a folder with a SKILL.md. That's the whole format. Building one takes ten minutes; building one that *triggers reliably* takes a little care.

The anatomy

---
name: release-notes
description: Use when asked to write release notes or a changelog from recent commits.
---

# Writing release notes

1. Run `git log --oneline` since the last tag.
2. Group commits into Features / Fixes / Internal.
3. Write one plain-language line per change — no commit hashes, no jargon.
4. Lead with the change users will notice most.

Two rules make or break it:

The description decides activation. Claude matches the user's request against it. Write it as the request itself: "Use when asked to…" — not a marketing blurb.

The body is instructions, not documentation. Imperative steps, concrete commands, explicit output format. You are programming the agent in prose.

Structure for bigger skills

Keep SKILL.md under ~150 lines; push detail into supporting files the skill references:

release-notes/
  SKILL.md          ← the core loop
  style-guide.md    ← referenced: "follow style-guide.md"
  examples.md

Claude reads referenced files on demand — this keeps the always-loaded part small.

Test it

Publish it

Push the folder to a public GitHub repo, and anyone can install it:

npx skills add you/your-repo --skill release-notes

Once it's public it will be picked up by the registries — and by our directory, where real install counts show you whether it's earning adoption.