How to Create a Claude Skill: SKILL.md Step by Step

Wondering how to create Claude skills? Here's the short version: a Claude skill is a folder containing a SKILL.md file — YAML frontmatter with a name and description, followed by markdown instructions. Put that folder in ~/.claude/skills/ (personal) or .claude/skills/ (project), and Claude Code reads the metadata at startup, then loads the full instructions only when a task matches the description.

That's the entire mechanism. The hard part isn't the file format — it's writing a description that triggers reliably and instructions that hold up under real use. This guide walks through everything you need to create a Claude skill from scratch: scaffolding the folder, writing frontmatter that works, adding scripts and reference files, testing locally, and publishing so your team can install it.

How to Create Claude Skills: What You Need First

Before you write SKILL.md, get three things in place:

1. Claude Code installed and working. Skills are loaded by the harness, so you need a functioning install to test against.
2. A recurring task worth encoding. The best skills capture something you'd otherwise re-explain every session: your commit conventions, a deployment runbook, a code review checklist. If you've typed the same instructions into chat three times, that's a skill.
3. A mental model of how skills load. Claude doesn't read your whole skill up front. At session start it sees only each skill's name and description — a few dozen tokens per skill. When a request matches a description, Claude pulls in the full SKILL.md body, and only then any extra files the body references. This progressive disclosure is why the description matters more than anything else you'll write.

Skills live in one of two places depending on scope:

If you're new to the concept entirely, start with our overview of what agent skills are and come back — the rest of this post is hands-on.

Step 1: Scaffold the Skill Folder and Frontmatter

Create a folder named after your skill, containing a single SKILL.md:

mkdir -p .claude/skills/conventional-commits
touch .claude/skills/conventional-commits/SKILL.md

Naming rules: lowercase letters, numbers, and hyphens only, and the folder name should match the name field in frontmatter. Keep it short and descriptive — conventional-commits, not my-cool-git-helper-v2.

Now the minimal viable SKILL.md:

---
name: conventional-commits
description: Write git commit messages following the Conventional Commits spec. Use when committing changes, writing commit messages, or reviewing commit history.
---

# Conventional Commits

Format every commit message as: type(scope): subject

Allowed types: feat, fix, docs, refactor, test, chore.
Keep the subject under 72 characters, imperative mood, no trailing period.

Two fields are required: name and description. Everything after the closing --- is the instruction body Claude loads when the skill activates. That's a complete, working skill — you could stop here and it would function. For the full field reference, including optional frontmatter, see the SKILL.md format guide.

Step 2: Write a Description That Actually Triggers

This is where most custom Claude skills fail. Remember: at selection time, Claude sees only the name and description. If the description doesn't clearly signal when to use the skill, the body never loads — no matter how good it is.

Skill description best practices come down to three rules:

1. State what the skill does AND when to use it. A description that only says what it does gives Claude no matching surface for real requests.

# Too vague — never triggers
description: Helps with commits.

# What + when — triggers reliably
description: Write git commit messages following the Conventional Commits spec. Use when committing changes, writing commit messages, or when the user asks to "commit this" or "clean up the commit history."

2. Include the exact phrases people actually type. If your teammates say "cut a release," put "cut a release" in the description — not just "manage the release process." Trigger matching works on the user's language, not yours.

3. Write in third person and stay concrete. "Generates database migration files for Drizzle ORM. Use when adding or modifying tables, columns, or indexes" beats "I can help you with your database needs."

Descriptions can be up to 1024 characters, but aim for two to four tight sentences. If you find yourself cramming ten unrelated triggers into one description, you probably have two skills — split them.

Step 3: Add Instructions, Scripts, and Reference Files

With triggering handled, invest in the body. Good instruction bodies share a shape:

• Lead with the procedure, not background. Claude reads this mid-task; it needs steps, not an essay.
• Show concrete examples — a correct commit message, a filled-in template, expected command output.
• State failure handling explicitly. What should Claude do when the lint script fails or the input is ambiguous?
• Keep SKILL.md under ~500 lines. Past that, split detail into reference files.

A skill doesn't have to be a single file. It can be a folder package with docs, scripts, and templates alongside SKILL.md:

conventional-commits/
├── SKILL.md
├── references/
│   └── examples.md
└── scripts/
    └── lint-commit.sh

Link the extras from SKILL.md with relative paths and tell Claude when to use them:

## Validating

Run `scripts/lint-commit.sh "<message>"` before finalizing any commit.
For fifty worked examples across every commit type, read references/examples.md.

Reference files follow the same progressive-disclosure model: they cost zero context until Claude actually opens them. This is how you write SKILL.md files that stay lean while backing deep workflows — the entry point is a router, the depth lives in the folder. On localskills.sh, skills are folder packages end to end: each published version can bundle docs, scripts, and templates up to 100 MB and 500 files.

Step 4: Test and Debug Your Skill Locally

Never assume a skill works because the file parses. Test the triggering, then the behavior:

1. Start a fresh Claude Code session. Skills are scanned at startup, so a running session won't see a skill you just added.
2. Phrase a request the way a real user would — without naming the skill. Say "commit these changes," not "use the conventional-commits skill." You're testing whether the description matches natural language.
3. Verify activation. Ask "which skills do you have available?" to confirm the skill is registered, then watch whether Claude actually reads SKILL.md when you give it a matching task.
4. Test the unhappy path. Give it ambiguous input, a failing script, an edge case. Vague instructions reveal themselves here.

If the skill registers but never activates, the fix is almost always the description — rewrite it with more concrete trigger phrases and retest in a fresh session. If it doesn't register at all, check the usual suspects: invalid YAML frontmatter (a stray colon or unquoted special character), a missing name or description field, or the folder sitting in the wrong directory. For a systematic walkthrough of every failure mode, see our guide to fixing Claude skills that don't trigger.

Step 5: Publish and Share Your Skill

A skill sitting in your home directory helps exactly one person. Publishing it to a registry gives it versioning, discoverability, and a one-command install for everyone else:

npm install -g @localskills/cli
localskills login
localskills publish --name your-org/conventional-commits

Publishing on localskills.sh gets you a few things that a gist or a copy-pasted folder can't:

• Versioning with rollback. Every publish cuts a new version; if an update breaks a workflow, roll back.
• Visibility controls. Public for the community, private for your org, or unlisted for a shareable-but-hidden link.
• Multi-tool output. One published skill installs into several tools at once — the CLI writes each tool's native format, so the same source becomes .claude/skills/ for Claude Code, .cursor/rules/ (.mdc) for Cursor, and .windsurf/rules/ for Windsurf:

localskills install your-org/conventional-commits --target claude cursor windsurf

• Download analytics, so you can see whether the skill is actually being adopted.

Your published skill gets a canonical URL like localskills.sh/your-org/git/conventional-commits, and teammates install it by that identifier. For the full walkthrough — account setup, org namespaces, CI publishing — see publish your first skill in under 5 minutes or the docs.

FAQ: How to Create Claude Skills

Where do Claude skills live on disk?

Personal skills go in ~/.claude/skills/<skill-name>/SKILL.md and apply across all your projects. Project skills go in .claude/skills/<skill-name>/SKILL.md inside the repo, get committed to version control, and load for every contributor. Skills can also arrive via plugins or a registry install.

What's the difference between a skill and CLAUDE.md?

CLAUDE.md is always in context — every instruction in it costs tokens on every request, whether relevant or not. A skill costs only its name and description until a matching task loads the body. Put universal, always-true project facts in CLAUDE.md; put task-specific procedures in skills.

How long should a SKILL.md file be?

Keep the body under roughly 500 lines. The description can be up to 1024 characters, but two to four sentences is the sweet spot. When a skill outgrows one file, move detail into reference files in the skill folder and link them with relative paths — they load on demand.

Can a Claude skill include scripts and other files?

Yes. A skill is a folder, and anything in it — shell scripts, templates, reference docs — ships with the skill. Reference SKILL.md's siblings by relative path and state when Claude should run or read each one. Published as a package on localskills.sh, a version can bundle up to 100 MB across 500 files.

Do custom Claude skills work in tools other than Claude Code?

The SKILL.md format is Claude Code's, but the underlying instructions usually aren't Claude-specific. Publish once to a registry like localskills.sh and install with --target cursor claude windsurf — the CLI translates your skill into each tool's native rules format, so Cursor, Windsurf, and others get the same guidance without hand-maintained copies.

---

Ready to share what you just built? Create a free localskills.sh account and publish your first skill in minutes.

npm install -g @localskills/cli
localskills login
localskills publish