How to Write Your Own Claude Skill: SKILL.md From Scratch

You’ve installed skills; now you want to write one — for your team’s conventions, your niche workflow, or public release. Authoring is genuinely simple; authoring well has exactly three hard parts. This guide covers all of them.

Anatomy of a skill

A skill is a folder in ~/.claude/skills/ (or .claude/skills/ for project scope):

my-skill/
  SKILL.md        ← required: frontmatter + instructions
  reference/      ← optional: docs loaded on demand
  templates/      ← optional: files your skill uses

SKILL.md opens with frontmatter:

---
name: release-notes
description: Use when the user asks to write release notes,
  a changelog, or "what's new" from commits or a git tag range.
---

# Instructions
When generating release notes:
1. Group by user impact, not by commit order...

Everything after the frontmatter is instructions Claude follows once the skill activates.

Hard part #1: the trigger description

The description field is the only thing Claude reads when deciding whether to load your skill. Weak descriptions are the top failure mode in our testing — skills that never fire score zero on “triggers reliably” no matter how good their instructions are.

What works: name concrete user phrasings. Not “helps with documentation” but “use when the user asks to write release notes, a changelog, or ‘what’s new’.” Include synonyms, include the negative space (“do NOT use for API reference docs”), and keep it under ~500 characters. Think of it as writing a regex in prose.

Hard part #2: instructions that constrain, not inspire

Bad skills read like motivational posters (“write clear, engaging release notes!”). Good skills read like checklists an expert would follow under deadline. Compare the skills that top our rankings: TDD forbids writing implementation before a failing test; Humanizer enumerates specific constructions to remove. Constraints transfer; vibes don’t.

Practical rules: prefer numbered procedures over prose; state what NOT to do (models over-generate); put rarely-needed detail in reference/ files and tell Claude when to read them — this keeps the always-loaded part lean.

Hard part #3: testing

You are not done when it works once. Minimum test battery:

Trigger test — 5 phrasings that should activate it, 3 that shouldn’t.
Clean-install test — fresh directory, follow your own README.
Baseline comparison — same task with and without the skill. If you can’t tell the outputs apart, the skill isn’t earning its context.

This is, not coincidentally, most of our public methodology. The Skill Creator skill (9.6/10) automates a surprising amount of it — it scaffolds structure, optimizes your description for triggering, and runs evals. Meta, and the best tool for the job.

Distribution

Push to GitHub with the claude-skills topic — that’s how our crawler and most directories find new skills. A clear README with an install command doubles your adoption. And when it’s live, submit it to us: testing and listing are free, and a passing verdict with a score is the strongest trust signal an unknown skill can get.