How to Create Your First Claude Skill: A Step-by-Step Tutorial

You can build a working Claude skill in about fifteen minutes, and you only need a text editor to do it. A skill is just a folder with one Markdown file inside — no SDK, no build step, no framework. This tutorial takes you from an empty folder to a tested, shareable skill, one step at a time.

If you're not yet sure what a skill is, start with our primer: What Are AI Skills and How to Use Them. If you already understand the concept and just want to build one, you're in the right place.

We'll build a real, useful example as we go — a skill that writes clean Conventional Commit messages — so by the end you'll have something you actually keep using.

What you'll build

By the last step you'll have a skill called conventional-commits that:

• teaches your agent to write commit messages that follow the Conventional Commits standard,
• includes a small helper script that reads your staged changes,
• loads itself automatically whenever you ask for a commit message, and
• is packaged so you can drop it into any project or share it with your team.

The same recipe works for any skill — a release-notes writer, a brand-voice editor, a test generator. Pick your own task once you've done this one.

What is a Claude skill? A 90-second recap

A skill is a folder containing a SKILL.md file. That file has two parts:

1. Frontmatter — a short YAML block with a name and a description. The description is how the agent decides when to use the skill.
2. Body — plain-Markdown instructions the agent follows once the skill is loaded.

Optionally, the folder can also hold scripts the agent runs and reference files it reads on demand. Claude only loads what it needs, when it needs it — a design called progressive disclosure. That's the whole model, and you can read the deeper version in What Are AI Skills. Now let's build one.

Before you start

You'll need three things:

• A way to run Claude with skills. The easiest for this example is Claude Code, but the Claude app (with Skills turned on) or the API work too.
• A text editor. Any editor at all — a skill is just text files.
• Basic Markdown. Headings, lists, bold. If you can write a README, you can write a skill.

No programming is required for the skill itself. The optional helper script in Step 5 is a few lines of shell — copy it as-is if you don't write code.

Step 1 — Pick one narrow job

The single biggest predictor of a good skill is scope. One skill should do one job. "Help with git" is too broad, and the agent won't know when to use it. "Write a Conventional Commit message from staged changes" is sharp — the agent knows exactly when it applies.

Good first skills are tasks you already re-explain to Claude often: your commit format, your PR template, your preferred test style, your brand voice. We're using commit messages because everyone understands the output.

Step 2 — Create the folder and SKILL.md

Make a folder named after the skill (lowercase, hyphenated) with a SKILL.md inside:

mkdir -p conventional-commits
cd conventional-commits
touch SKILL.md

For Claude Code, the folder lives in your project at .claude/skills/conventional-commits/. That path is all Claude Code needs to discover it.

Step 3 — Write the frontmatter (the most important step)

Open SKILL.md and start with a YAML frontmatter block between two --- lines:

---
name: conventional-commits
description: Writes git commit messages that follow the Conventional Commits spec. Use when the user asks for a commit message, is committing staged changes, or mentions writing a commit.
---

Two rules decide whether your skill ever fires:

• name — lowercase letters, numbers and hyphens, kept short. It identifies the skill.
• description — this is the trigger. Write it in the third person, say plainly what the skill does and when to use it, and include the words a user would actually type ("commit message", "commit", "staged changes"). A vague description is the number-one reason a skill never loads.

Pro tip: read your description back as if you were the agent. If you can't tell from those two sentences exactly when to reach for the skill, neither can Claude. Rewrite until it's obvious.

Step 4 — Write the instructions

Below the frontmatter, write the actual playbook in Markdown. Be direct and specific — these are orders, not suggestions:

## How to write the commit message

1. Inspect the staged changes before writing anything.
2. Use the format: type(scope): subject
3. Choose the type from: feat, fix, docs, refactor, test, chore, perf.
4. Keep the subject under 50 characters, imperative mood ("add", not "added").
5. Leave a blank line, then a body that explains WHY, not what.
6. Note any breaking change with a "BREAKING CHANGE:" footer.

## Examples

feat(auth): add password reset flow
fix(api): handle null user on profile route
docs(readme): clarify install steps

Keep it focused. A tight one-page SKILL.md beats a sprawling one — and anything long or occasional belongs in a separate reference file, which is the next step.

Step 5 — Add scripts and reference files

This is what makes a skill more than a saved prompt: it can carry tools and extra context that load only when needed.

Add a helper script that pulls the staged diff, so the agent always works from your real changes:

conventional-commits/
|-- SKILL.md
`-- scripts/
    `-- staged-diff.sh

Inside scripts/staged-diff.sh:

#!/usr/bin/env bash
# Print the staged changes for the commit-message skill.
git diff --cached --stat
git diff --cached

Then point to it from SKILL.md so the agent knows it exists:

## Tools

Run scripts/staged-diff.sh to see the staged changes before writing the message.

For long reference material — a full style guide, an API table — drop it in a references/ folder and mention it the same way. Thanks to progressive disclosure, that file only enters the context when the agent decides it's relevant, so it costs you nothing the rest of the time.

Step 6 — Test your skill

Install it and try it:

• Claude Code: with the folder in .claude/skills/, stage a change (git add .) and ask: "write a commit message for my staged changes." Claude should load the skill and produce a properly formatted message.
• Claude app: enable the skill in your Skills settings, then make the same request.
• API or Agent SDK: attach the skill to your agent and send the request programmatically.

The tell-tale sign it worked: the output follows your rules without you pasting them in. If Claude ignores the skill, the description didn't match — which is the next step.

Step 7 — Iterate on the description

Ninety percent of "my skill won't trigger" problems are the description, not the instructions. If it didn't fire, widen the trigger phrases to match how you actually talk:

description: Writes git commit messages in the Conventional Commits format. Use whenever the user asks to commit, wants a commit message, mentions staged changes, or runs git commit.

If it fires at the wrong time, tighten it instead. Tuning the description is normal — treat it like SEO for your agent's attention.

Step 8 — Package and share it

A finished skill is portable by design. To share it:

1. Zip the folder and hand it to a teammate to drop into their own .claude/skills/.
2. Commit it to a public GitHub repo so anyone can clone or download it — this is exactly how the official skills from GreenSock, Vercel and Stripe are distributed.
3. Publish it to the marketplace. Submit your skill on PromptsRush, point it at your GitHub URL, and it gets a polished listing with a download button, install steps, and your name on it.

Ship it: if your skill solves a real problem, other builders want it. Submit it to the Skills Marketplace and it joins skills like the ones below.

A complete example skill

Here's the full SKILL.md in one place, ready to copy:

---
name: conventional-commits
description: Writes git commit messages that follow the Conventional Commits spec. Use when the user asks for a commit message, is committing staged changes, or mentions writing a commit.
---

# Conventional Commits

Write commit messages that follow the Conventional Commits standard.

## Steps

1. Run scripts/staged-diff.sh to inspect the staged changes.
2. Use the format: type(scope): subject
3. Pick the type from: feat, fix, docs, refactor, test, chore, perf.
4. Subject under 50 chars, imperative mood, no trailing period.
5. Blank line, then a body explaining WHY the change was made.
6. Add a "BREAKING CHANGE:" footer when relevant.

## Examples

feat(auth): add password reset flow
fix(api): handle null user on profile route
docs(readme): clarify install steps

That's a real, working skill. Change the name, description and rules and you have a template for anything.

Best practices that separate good skills from bad

• One job per skill. Narrow beats broad every time.
• Spend your time on the description. It controls whether the skill is ever used.
• Write imperatively. "Do X. Never Y." Agents follow direct instructions better than gentle suggestions.
• Keep SKILL.md short; push detail to reference files. Let progressive disclosure do its job.
• Study real skills. Read the SKILL.md in Stripe's skills or the Vercel skills and copy what works.

Common mistakes to avoid

• A vague description. "Helps with code" triggers either never or always. Be specific about the task and the moment.
• Cramming several jobs into one skill. Split them. Agents combine skills well; they handle monoliths badly.
• A wall of text. If your SKILL.md runs past a page or two of core rules, move the overflow into references/.
• Running an untrusted skill. Skills can execute code — read one before you install it, and only take skills from sources you trust.

Where to go next

You've built and shipped a skill — now scale the habit. Read What Are AI Skills and How to Use Them for the bigger picture, see whether Claude can build a full SaaS app alone for where agents are headed, and grab our Next.js prompts for Claude while you're building. Then browse the Skills Marketplace for ideas — and when your next skill is ready, submit it to share with everyone.