How to Build Your First Claude Code Skill in 30 Minutes (2026)

If you have Claude Code installed, you can write your first custom skill in 30 minutes. No coding. Just a folder, a markdown file, and a restart.

This guide walks through one complete example, a "commit reviewer" skill that triggers when you ask Claude to commit. Pick a real task you do often and adapt as you go.

What a skill actually is

A skill is a folder in your home directory that contains a SKILL.md file with two parts:

1. A frontmatter block at the top, name, description, when to trigger. 2. Markdown instructions — the rules Claude follows when the skill triggers.

That's it. No code, no build step, no installer. Claude Code scans ~/.claude/skills/ at session start, reads each skill's description, and surfaces the right skill at the right moment.

The whole system is plain files. You can edit a skill in any text editor.

Step 1: Decide what your skill should do (5 min)

Pick something repetitive. The best first skills come from instructions you keep typing into Claude Code.

Some examples:

• A commit reviewer skill that adds a checklist before any git commit
• A blog opener skill that follows your hook formula for new articles
• A bug report skill that asks the right diagnostic questions in order
• A meeting follow-up skill that drafts an email in your voice

For this walkthrough we'll build the commit reviewer. The trigger: any time you ask Claude to commit, it should pause, check a list of things, and only then write the commit.

Step 2: Create the folder (2 min)

Open your terminal. On Mac or Linux:

mkdir -p ~/.claude/skills/commit-reviewer
cd ~/.claude/skills/commit-reviewer

On Windows (PowerShell):

New-Item -ItemType Directory -Path "$env:USERPROFILE\.claude\skills\commit-reviewer" -Force
Set-Location "$env:USERPROFILE\.claude\skills\commit-reviewer"

The folder name becomes the skill's identifier. Use lowercase with hyphens.

Step 3: Write the SKILL.md (15 min)

Create a file called SKILL.md inside that folder. Open it in any editor.

The skill needs a frontmatter block first. This is the part Claude reads at session start to decide whether the skill is relevant.

---
name: commit-reviewer
description: Pre-commit checklist for git. Use before any git commit to verify the diff is clean, no secrets are included, and the commit message follows project conventions. Triggers when the user says "commit", "make a commit", "let's commit", or asks Claude to push changes.
---

The description matters a lot. Claude uses it to decide whether the skill is relevant to the current request. Two rules:

• Be specific about triggers. Don't write "for git stuff" — write "triggers when the user says 'commit', 'make a commit', 'let's commit', or asks Claude to push changes."
• State the value. The first sentence should explain what the skill does. Don't bury it.

After the frontmatter, write the instructions in plain English. Walk Claude through what to do, in order.

# Commit Reviewer

When the user asks you to commit, do not commit immediately. Run this checklist first.

## Step 1. Check the diff

Run `git status` and `git diff --staged` (or `git diff` if nothing is staged yet). Read the actual changes. Look for:

- Console.log / print statements left over from debugging
- TODO or FIXME comments added by accident
- Hardcoded secrets, API keys, or passwords
- Temporary test files that shouldn't ship
- Large files that should be in .gitignore (zip, mp4, sqlite, etc.)

If you find any of these, stop and flag them to the user before proceeding.

## Step 2. Stage only what belongs

If files are unstaged, don't blanket `git add .`. List what changed and ask which files to include unless the user already specified.

## Step 3. Write the commit message

Follow this format:

type: short summary in present tense (max 60 chars)

Optional body explaining the WHY in 2-3 sentences.

Type is one of: feat, fix, refactor, docs, test, chore, style.

## Step 4. Commit

Run the commit. Show the user the result. Do not push automatically, wait for them to ask.

## Things that should never end up in a commit

- .env, .env.local, credentials.json
- Files matching *_key, *_secret, *.pem
- Personal IDE configs (.vscode/settings.json with personal paths)
- Build artifacts (dist/, build/, .next/)

Save the file.

That's your skill. Three things to notice:

• It uses regular markdown, no special syntax beyond the frontmatter.
• It describes what to do and what to avoid, both useful.
• It ends with a concrete "never do this" list, those tend to be the most useful sections in any skill.

Step 4: Restart Claude Code and test (5 min)

Quit and reopen Claude Code. The session has to start fresh to pick up the new skill.

Open any project and type:

let's commit these changes

If the skill is wired up correctly, Claude should pause and walk through the checklist. You'll see it run git status, read the diff, flag any issues, and propose a commit message in the format you specified.

If nothing happens, check the frontmatter description. The most common bug is a vague description that doesn't include the trigger words. Add the exact phrases you'll use ("commit", "let's commit", "make a commit") and try again.

Step 5: Iterate (3 min, and forever)

The first version of any skill will miss things. After a week of use, you'll notice patterns:

• Claude keeps skipping step 2 → make step 2 louder, add "REQUIRED" tag
• Claude over-commits when you wanted just a draft → add explicit "wait for confirmation" line
• The commit messages drift → add an example of a good message

Open SKILL.md and edit. No rebuild, no install. Save the file, restart Claude Code, the new rules apply.

This iteration loop is the biggest reason to start with skills before MCP servers, the feedback is immediate.

Common mistakes

Description too vague. "For git stuff" won't trigger reliably. Be specific about the words you use.

Instructions written like a feature spec. Write conversationally, like you're teaching a smart intern. "When the user asks you to X, first do Y. If you find Z, flag it." Not "Function: Pre-Commit Validation Module."

Trying to do too much. A skill should have one clear job. If your SKILL.md is over 500 lines, you have two skills pretending to be one.

Hardcoded paths or assumptions. Skills run in many different projects. Don't assume there's always a /src folder or a specific commit format. Detect what's there.

No "what not to do" section. The negative space is often more important than the positive. List the failure modes.

What to build next

After your first skill, the obvious extensions:

• A blog-opener skill that follows your voice rules
• A PR-review skill that runs through your code review checklist
• A bug-triage skill that asks the right questions in order
• A meeting-notes skill that formats summaries in your team's template

Each one is the same recipe: a folder, a SKILL.md with frontmatter, a checklist in markdown.

For more advanced skills, ones that call external APIs or hold state, you'll eventually want MCP Builder (a different Anthropic-shipped skill that scaffolds MCP servers). But for 90% of "make Claude better at my workflow" tasks, plain skills are enough.

FAQ

Do skills work in Claude.ai (the web app)? No. Skills are a Claude Code feature. The web Claude has Projects with custom instructions, which serve a similar purpose but aren't the same system.

Do I need to install anything to write a skill? No. Claude Code reads skill folders automatically. If you can edit a text file, you can write a skill.

Can I share skills with my team? Yes, push the skill folder to a shared git repo, teammates clone it into their ~/.claude/skills/. There's no central registry yet, but plain folders are easy to distribute.

What's the difference between a skill and a slash command? Slash commands are explicit, you type /command. Skills trigger automatically based on context. Skills are better for "always-on" behavior; slash commands are better for explicit one-off operations.

Can a skill run shell commands? A skill is markdown, it doesn't execute anything itself. But the instructions inside the skill can tell Claude to run shell commands. So "run git status first" works because Claude does the running.

How many skills can I have installed at once? Practically, dozens. Claude is good at picking the right one based on the description. The cost is a bit of extra context at session start, keep descriptions tight and you'll be fine.