Project 13 — Author an Agent Skill

Enforces: skill anatomy, the description-as-trigger, bundled resources, and lazy loading (from introduction-to-agent-skills) Surface: Claude Code (terminal) · Time: ~60 min · Difficulty: 🟡 intermediate

Why this project

A skill is a capability Claude loads on demand — it sits idle as just a one-line description until the model decides it's relevant. That description is the whole game: it's the prompt that gets Claude to reach for the skill at the right moment and ignore it otherwise. This project makes you write one for a task you actually repeat, bundle a resource, and tune the trigger until it fires reliably.

What you'll build

A real skill directory under .claude/skills/ containing a SKILL.md (frontmatter name/description + a short instruction body) and at least one bundled script or template, for a task you do often — and the evidence that Claude auto-triggers it.

Steps

Pick a recurring task — Something you genuinely repeat: "scaffold a new React component," "write a conventional changelog entry," "convert this table to our report format." Concrete and bounded beats clever.
Create the skill dir — .claude/skills/<your-skill>/ with a SKILL.md and a bundled resource:
```
.claude/skills/changelog-entry/
  SKILL.md
  templates/entry.md
```

Write SKILL.md — Frontmatter first; the description is critical (Claude reads only this until it triggers). Lead with concrete triggers AND negative triggers:

---
name: changelog-entry
description: >
  Use when the user wants to add or write a CHANGELOG entry, release note,
  or "what changed" summary for a merged change. Do NOT use for commit
  messages or PR descriptions — those are separate.
---

# Changelog Entry

When invoked:
1. Read `templates/entry.md` for the exact house format.
2. Ask for the version and category (Added / Fixed / Changed) if unstated.
3. Append the new entry under the right heading; keep entries one line, imperative mood.

Keep the body short — push the format detail into templates/entry.md and reference it by relative path so it's read on demand, not always in context.

Verify auto-trigger — Start a fresh claude session. Phrase a request the natural way ("add a changelog line for the refund fix") — without naming the skill. Confirm Claude loads it and reads the bundled template.
Refine the description — Try two phrasings that should trigger and one that shouldn't. If it misfires or fails to fire, edit the description (add triggers, sharpen negatives) and re-test until all three behave. This tuning loop is the core skill of the project.
Commit — Add the whole skill directory so the team inherits the capability.

Acceptance criteria — you're done when

A SKILL.md exists with valid name/description frontmatter and a short instruction body.
The skill bundles at least one script or template, referenced by relative path from the body.
Claude auto-triggers the skill from a natural request, without the skill being named.
You tuned the description so two should-fire phrasings fire and one should-not phrasing doesn't.
You can explain why a skill is cheaper-when-idle than a subagent or a fat system prompt.
You journaled the wording change that fixed your trigger in learning-journal-template.

Stretch goals

Add an executable helper to scripts/ and have the skill body invoke it.
Write a second skill and add an explicit negative trigger so the two never collide.
Move the skill to ~/.claude/skills/ and confirm it's now available across all your projects.

Self-assessment rubric

Level	Signal
🟢 Got it	You write descriptions that trigger precisely, and you instinctively push detail into bundled files instead of the body.
🟡 Almost	The skill works but you had to name it explicitly, or it over-triggers on unrelated requests.
🔴 Revisit	The skill never fires automatically. Re-watch introduction-to-agent-skills and re-read the description guidance in agent-skills.