Custom skills

You met skills briefly in Module 3 as "the bigger version of slash commands." This lesson goes deeper: how to design a skill that's actually worth the structure, how to package supporting files, and the moment you should turn a habit into a formal skill.

When to turn something into a skill

There's no point in formalising a workflow until it's proven. The rough threshold:

• You've done the workflow three or more times by hand-prompting Claude.
• Each time you typed roughly the same instructions, with a few variables.
• You can articulate the steps clearly enough that they'd be useful to someone else doing the same thing.

If those three are true, write the skill. The five minutes you spend will pay back across every future use.

Anatomy of a skill

A skill is a folder, usually at .claude/skills/<name>/, containing at minimum a SKILL.md file:

---
name: release-notes
description: Generate release notes from commits since the last tag.
  Use when the user asks for release notes, a changelog entry,
  or a "what shipped" summary.
allowed-tools: Bash(git log:*), Bash(git tag:*), Read, Glob
---

You are generating release notes for a software project. Follow these
steps:

1. Find the most recent git tag with "git tag --sort=-creatordate | head -1".
2. List commits since that tag with "git log <tag>..HEAD --oneline".
3. Group commits into: Features, Fixes, Refactors, Other.
4. Skip merge commits and commits that say "wip" or are clearly tiny.
5. Write a tidy Markdown changelog entry with today's date.
6. Show me the result for review. Don't write it to a file unless I ask.

Four important parts:

• name — what the skill is called. Used to invoke it directly.
• description — what the skill is for, and whenClaude should surface it. The trigger phrases you list ("use when the user asks for...") are how Claude knows to suggest this skill when relevant.
• allowed-tools — the tool allowlist. Skills can scope themselves: read-only, edit-only, no shell execution, etc. This is a real safety feature, not just metadata.
• Body — the actual instructions, in Markdown. Be specific. Number steps. Tell Claude what to output and what to skip.

Triggering on intent, not just name

Slash commands fire only when explicitly typed: /release-notes. Skills can also be triggered by what the user asks. If someone says "hey can you draft a changelog for the past two weeks?" Claude reads the description on each available skill, notices that release-notesmentions "changelog entry," and offers it.

That's why the description matters so much. Write it as a list of plausible user phrasings, not a marketing blurb. The better the description matches real requests, the more often the skill earns its place.

Adding supporting files

A skill folder can include more than just SKILL.md. Templates, example outputs, reference data — anything the skill wants to reference goes alongside:

.claude/skills/release-notes/
├── SKILL.md
├── template.md         # the changelog format we like
└── examples/
    ├── good.md
    └── bad.md

The skill's instructions can then say things like "use template.mdas the layout" or "compare your draft to examples/good.mdbefore finishing." Claude reads those files as part of running the skill.

Personal vs. team skills

Two layers to put skills in:

• Project-level — <project>/.claude/skills/. Committed to git. Shared with the team. Best for workflows specific to this codebase.
• Personal — ~/.claude/skills/. Lives on your machine. Best for your individual habits that don't need to be team-wide.

A common pattern: try out a skill personally first, polish it, then promote it to project-level once it's proven. The commit message becomes its own kind of release notes.

Designing a skill that works

The skills that get used a lot share traits:

• One job. A skill that tries to do release notes and deploy and notify Slack is fragile. Three small skills is better than one big one.
• Numbered steps. The body of the skill should be ordered instructions, not prose. Claude follows them more reliably.
• Explicit outputs.Say what the skill should produce. "Show me the result." "Write to file X." "Open a PR with this body." Removes ambiguity.
• Stopping points. Tell the skill where to pause for confirmation, especially before destructive actions.

Skills as institutional memory

The deepest reason to build skills is not productivity — it's knowledge capture. The senior engineer's instinct for " here's how we ship a release on this team" becomes a skill, and now every contributor (human or AI) does it the same way. The team's tribal knowledge is no longer trapped in one person's head.

Treat your skills folder as the lightweight runbook of the project. If a new hire needs to know how to do something, the answer should increasingly be "run that skill."