Build your first Claude Code skill (by hand, in 5 minutes)

A skill is a folder of instructions Claude Code loads on its own when a task matches. You don't call it — Claude reads the skill's description, decides it's relevant, and pulls in the full instructions. Think "reusable playbook your agent auto-discovers."

TL;DR: make ~/.claude/skills/<name>/SKILL.md with two frontmatter fields (name, description) + a markdown body. The description is the whole game — it's the only thing Claude sees when deciding whether to use the skill, so spell out exactly WHEN to trigger and include real phrases a user would type.

---

The anatomy

.claude/skills/
  conventional-commits/
    SKILL.md          ← required; frontmatter + instructions
    (optional) scripts/, templates/, references/ …

SKILL.md is just markdown with a YAML frontmatter block on top:

---
name: conventional-commits
description: >
  Write git commit messages in Conventional Commits format
  (feat:, fix:, chore:, docs:, refactor:…). Use whenever the user asks to
  "commit", "write a commit message", "commit my changes", or is staging code.
---

# Conventional Commits

When asked to commit, do this:

1. Run `git diff --staged` (or `git status` + `git diff`) to see what changed.
2. Pick ONE type: feat | fix | docs | style | refactor | test | chore.
3. Format: `<type>(<optional scope>): <short imperative summary>`
   - Summary ≤ 72 chars, lowercase, no trailing period.
   - Add a blank line + body only if the "why" isn't obvious.
4. Show the message and run the commit.

## Examples
- `feat(auth): add password reset flow`
- `fix(api): handle empty response from /users`
- `chore: bump deps to latest patch`

That's a complete, working skill. Two fields, then plain instructions.

---

The one rule that matters: the description

Claude never sees the body until it has already decided to use the skill — and it decides purely from description. So:

Rules of thumb:

• State WHEN, not just what. "Use when…" + concrete trigger phrases.
• Quote the words a user actually types. Those become the match signal.
• Be narrow. One skill = one job. A vague catch-all rarely fires at the right time.
• name: lowercase, hyphens, matches the folder name.

---

Where it lives

Use the project folder for anything repo-specific (this codebase's deploy steps, its test conventions). Use the home folder for your personal habits.

---

Test it

1. Create the folder + SKILL.md above.
2. Start (or restart) Claude Code in that directory.
3. Type a trigger phrase — e.g. "commit my changes".
4. Claude should load the skill and follow your steps. If it doesn't fire, your description is too vague or missing the words you actually typed — tighten it and retry.

Quick sanity check that Claude sees it: ask "what skills do you have available?"

---

Where this fits

Skills are how you stop re-explaining the same workflow every session. Anything you've typed to Claude more than twice — your commit style, your PR template, how you write tests, your deploy checklist — belongs in a skill. Start with one, keep it small, add more as patterns repeat.

Shortcut

Don't want to hand-write frontmatter? StackScout's skill-creator generates a correct SKILL.md (name, tuned description, body structure) from a one-line description of the job — then you just tweak the steps.

---

Guide by StackScout · more free AI-dev guides, skills & repo picks → stackscout.app