Skip to main content

Write Your First Skill End-to-End

Intermediate
What you'll learn
  • Build a working Skill from scratch and prove it actually activates
  • Write a description that triggers at the right time — the one field that decides whether a skill ever runs
  • Decide when to add a helper script for deterministic data gathering
  • Diagnose a skill that never fires, and know the three pitfalls that cause it

Let's build a working Skill from scratch and prove it activates. We'll make a small "changelog entry" skill — generic and reusable.

Step 1 — Create the folder​

Create the skill folder

mkdir -p .claude/skills/changelog-entry

(Use ~/.claude/skills/… for a personal skill across all projects.)

Step 2 — Write SKILL.md​

.claude/skills/changelog-entry/SKILL.md:

---
name: changelog-entry
description: Use when the user wants to turn recent git commits into a Keep a Changelog entry.
---

# Changelog Entry

When asked for a changelog entry:
1. Run `git log --oneline -20` to see recent commits.
2. Group them into Added / Changed / Fixed / Removed (Keep a Changelog style).
3. Write concise, user-facing bullets (not raw commit messages).
4. Output only the formatted entry.

The description is the trigger — write it as "Use when…" so Claude loads it at the right time.

Step 3 — (Optional) add a helper script​

Skills can ship scripts. Add scripts/recent.sh and reference it from SKILL.md if you want deterministic data gathering:

#!/usr/bin/env bash
git log --oneline -20

Step 4 — Prove it triggers​

Start a session and try the prompt below. Claude should recognize the intent, load the skill, and follow its steps. If it doesn't activate, your description probably isn't specific enough about when to use it — sharpen it.

Prove the skill triggers

Draft a changelog entry for recent work.

Step 5 — Share it​

Bundle it (with others) into a plugin so your team installs it in one step — or contribute it to AILmanac's skill packs.

Pitfalls​

  • Vague description → never triggers (or triggers always). Be specific.
  • Too much in one skill → keep it one clear job.
  • Secrets in a shared skill → never; see Reviewing Third-Party Code.
Key takeaways
  • A skill is a folder plus a SKILL.md — .claude/skills/<name>/ for the project, ~/.claude/skills/ for every project
  • The description is the trigger. Write it as "Use when…" so Claude loads it at the right moment
  • Skills can ship scripts — use one when you want deterministic data gathering instead of Claude improvising the command
  • Prove it works by prompting the intent, not by naming the skill. If it doesn't fire, the description isn't specific enough about WHEN
  • Keep one skill to one clear job, and never put secrets in a skill you share

Check yourself

0/3
  1. Your skill never activates, no matter what you ask. Which field is almost certainly the problem?
  2. You want a changelog skill available in every project you work on, not just this one. Where does it go?
  3. Why ship a helper script like scripts/recent.sh with a skill?

Next​