Claude Code Skills Tutorial: Build Your First Skill in 20 Minutes

What you'll build

By the end of this Claude Code skills tutorial, you will have a working skill that automates one of the most common developer tasks: writing conventional-commit messages from a git diff. The skill will load on demand, scan your staged changes, and produce a properly-formatted commit message including type, scope, and description.

Twenty minutes from start to finish. Real working code. The pattern you will use here is the same pattern that powers production-grade skill libraries with hundreds of skills. If you want the conceptual background first, our Claude Code skills explained guide covers what skills are and when to build them.

Prerequisites

Three things before you start:

1. Claude Code installed and a project with .claude/ directory. If you do not have one yet, our Claude Code setup guide walks through the install.
2. A git repository with some uncommitted changes. We need real diff content to test against.
3. Five minutes of focus. The tutorial is short but every step matters.

Step 1: Create the skill directory

Skills live in .claude/skills/{category}/{skill-name}/. The category is your choice, the skill name becomes the invocation slug.

Run this from your project root:

mkdir -p .claude/skills/git/conventional-commit

The directory is what tells Claude this is a skill. The category (git/ here) makes it easy to organise as your library grows.

Step 2: Create SKILL.md

Inside that directory, create the file Claude will read when the skill loads:

touch .claude/skills/git/conventional-commit/SKILL.md

Now open the file and paste this content. The structure below is the minimum-viable skill format. We will explain each section after.

# Conventional Commit Message Generator

Generates a conventional-commit-format commit message from staged
git changes. Use whenever the user asks for a commit message, says
"write the commit," or finishes a chunk of work and is about to
commit.

## When to use this skill

Trigger this skill when:
- The user explicitly asks for a commit message
- The user says "commit this" or "write the commit"
- A discrete task has finished and changes are staged
- Multiple files have been edited and the user mentions committing

## What this skill does

1. Run `git diff --staged --stat` to see what changed
2. Run `git diff --staged` to see the actual changes
3. Determine the type from the changes:
   - `feat` if new functionality was added
   - `fix` if a bug was repaired
   - `refactor` if structure changed without behaviour change
   - `docs` if only documentation files changed
   - `test` if only test files changed
   - `chore` for build, deps, config
4. Determine the scope from the most-changed directory
5. Write the description: imperative mood, under 72 chars,
   no trailing period

## Output format

Output the commit message in this format, ready to paste:

git commit -m "<type>(<scope>): <description>"

For multi-paragraph commits (more than 5 files), include a body:

git commit -m "<type>(<scope>): <description>

- bullet point per logical change
- max 5 bullets
- explain *why*, not *what*"

## Hard rules

- Never run `git commit` automatically. Output the command for the user.
- Never include co-authored-by tags unless the user asks.
- If staged changes mix unrelated work, suggest splitting into multiple commits.
- If the diff is over 500 lines, ask the user to confirm scope before writing.

That is your first skill.

Step 3: Test the skill

Stage some changes in your repo and ask Claude:

Write the commit

Claude should locate the skill (the SKILL.md file in .claude/skills/git/), read its instructions, run the diff commands, and output a properly-formatted commit. If it does not find the skill, the most common issue is the directory path.

If the skill loads but the output is not what you wanted, edit the SKILL.md and refine. Skills are iterative. Each refinement makes the next invocation cleaner.

Step 4: Why this structure works

Three things in that SKILL.md are doing the work:

The "When to use" section. Claude reads skills on demand. The trigger conditions tell it when to load this one without you typing the skill name explicitly. Get this right and the skill becomes invisible automation. Our Claude Code skills guide breaks down exactly how this matching works and how to write a description that fires reliably.

The "What this skill does" steps. Numbered steps are easier for Claude to follow than prose. The model treats them as a procedure, not a suggestion.

The "Hard rules". Negative instructions ("never X") work better than positive ones ("always Y") for catching edge cases. The "never run git commit automatically" rule is what stops the skill from being a destructive tool.

This three-section pattern is the load-bearing structure for every skill we ship in Claudify. Trigger conditions, numbered steps, hard rules. Everything else is optional.

Step 5: Add a second skill

Now that you have one skill working, the second one is faster. Repeat the pattern:

mkdir -p .claude/skills/git/branch-namer
touch .claude/skills/git/branch-namer/SKILL.md

Inside, write a similar structure for naming git branches based on the current task. The "When to use" might be: "the user is about to create a branch and has described the work." The steps follow the same numbered procedure pattern. The hard rules might include "never use spaces" and "always include the issue number if one is mentioned."

The second skill takes roughly half as long as the first because the structure is now muscle memory. By the fifth skill, you will write them in five minutes.

What happens at scale

Production-grade skill libraries have 50-200 skills. Three things change at that scale:

Categorisation matters. With 200 skills, finding the right one becomes an organisational problem. Top-level categories (git/, database/, frontend/, testing/) become essential.

Trigger conflicts emerge. Two skills both want to fire on "write the commit." Specificity in trigger conditions becomes important. The narrower the trigger, the cleaner the routing.

Maintenance becomes a workstream. Skills age. Test patterns shift, library APIs change, conventions update. A monthly skim through your skill library to deprecate stale ones is a real maintenance task.

A pre-built skill library with these patterns already in place is exactly what Claudify ships. 1,727 expert skills across 31 categories, organised, tested, and ready to compose with your own.

Common mistakes in your first 10 skills

Three patterns to avoid:

Skills that are actually agents. A skill loads on demand and follows instructions. An agent has its own persistent context and decision-making. If your "skill" needs to remember things across invocations or reason about which other skill to call, you actually want a custom agent.

Trigger conditions too broad. "Use this skill when working with files" is too vague, it will fire on everything. "Use this skill when the user asks to refactor a React component" is specific enough to route cleanly.

Hard rules as soft preferences. "Try to keep commits short" is not a hard rule, it is a wish. "Reject if commit message is over 72 characters" is enforceable.

What to build next

Three skill ideas worth your second hour:

Code review skill. Scans staged changes against your team's review checklist. Fires when the user asks for a review.

Migration writer. Generates a Drizzle/Prisma migration from a schema diff. Fires when the user changes the schema.

API endpoint scaffolder. Generates the boilerplate for a new endpoint matching your project's conventions. Fires when the user asks to add a route.

Each one follows the same three-section pattern. The first one takes 20 minutes; by the fifth, you will be done in 5.

Skills versus other Claude Code features

Three closely-related features that solve different problems:

Feature	When to use
Skill	A repeatable procedure with clear trigger conditions
Agent	A persistent role with its own memory and decision-making
Hook	Deterministic enforcement that runs every time, no model in the loop

A clean Claude Code setup uses all three. Skills for procedures, agents for roles, hooks for guardrails.

Next steps

You now know the skill format. The leverage compounds the more skills you ship and the better-organised they are.

Get Claudify. The Claude Code operating system that ships with 1,727 expert skills across 31 categories, all in this exact structure.