How to Create Your First Claude Skill: A Step-by-Step Tutorial
Build a working Claude skill from scratch — plan it, write the SKILL.md and frontmatter, add a script, test it in Claude Code, and publish it to the marketplace.
Build a working Claude skill from scratch — plan it, write the SKILL.md and frontmatter, add a script, test it in Claude Code, and publish it to the marketplace.
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.
By the last step you'll have a skill called conventional-commits that:
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.
A skill is a folder containing a SKILL.md file. That file has two parts:
name and a description. The description is how the agent decides when to use the skill.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.
You'll need three things:
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.
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.
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.
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:
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.
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.
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.
Install it and try it:
.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.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.
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.
A finished skill is portable by design. To share it:
.claude/skills/.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.
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.
SKILL.md in Stripe's skills or the Vercel skills and copy what works.SKILL.md runs past a page or two of core rules, move the overflow into references/.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.
8 questions answered
What Are AI Skills and How to Use Them (2026 Guide)
May 31 · 10 min
How Developers Are Using Claude 4.8 for Vibe Coding
May 30 · 10 min
Can Claude Opus 4.8 Build a Full SaaS App Alone?
May 30 · 9 min
How to Use Claude Design: 25+ Working Prompts (2026)
May 28 · 14 min
Claude 4.8 vs Claude 4.7: What Actually Improved (2026 Benchmarks)
May 28 · 11 min