How to Write Your First Claude Code Skill in 2026

The first skill I wrote was fifteen lines of Markdown and no code at all. It just taught Claude Code how our team formats commit messages, so I stopped re-explaining it every session. That's the thing nobody tells you: your first skill doesn't need to be clever. It needs to save you from typing the same instructions twice.

A Claude Code skill is a folder with one required file, SKILL.md, that tells the agent what the skill does and when to use it. Match a request to that description and the agent loads the instructions and follows them. Optionally the folder holds scripts and reference files. That's the entire model. Here's how to build one from scratch.

What you're actually building

A skill with just a folder and a SKILL.md is a real, working skill. Everything else is optional weight you add only when the job calls for it.

Step 1: Pick a job you repeat

Don't start with something ambitious. Start with a thing you explain to your agent over and over. Formatting rules for your project. The steps to prep a release. The house style for your blog. The tone your support replies use. A skill earns its keep by absorbing repetition, so the best first candidate is whatever you're tired of retyping.

Write that job down in one sentence. If you can't say what the skill does in a sentence, it's two skills.

Step 2: Create the folder and SKILL.md

Make a folder named for the skill, kebab-case, and put a SKILL.md at its root. The file starts with a small block of frontmatter, then your instructions:

---
name: commit-style
description: Format git commit messages in our team's house style. Use whenever writing or editing a commit message.
---

# Commit Style

Write commit messages as:
- A short imperative summary, under 60 characters
- A blank line
- A body explaining why, not what
- Reference the ticket as [PROJ-123] at the end

The description is the most important line in the file. It's what the agent reads to decide whether to load the skill, so write it for matching, not for marketing. Say plainly what the skill does and when to use it.

Step 3: Test it on a real request

Open Claude Code and make a request that should trigger the skill. For the example above, ask it to write a commit message. If the skill loaded, the output follows your rules. If it didn't, the usual culprit is a vague description that didn't match your phrasing.

This is the loop: make a request, watch what the agent does, tighten the description or the instructions, try again. Testing on your actual work beats imagining edge cases, because the gaps show up fast when you use it for real.

Step 4: Add a script only if you need one

Instructions-only skills cover a surprising amount. You reach for code when the skill needs to do something the agent can't do by reasoning alone: call an API, parse a file, run a calculation, hit a database. When that's the case, drop a script in the folder and point to it from SKILL.md, telling the agent when to run it.

Keep scripts small and single-purpose. A skill that shells out to one clear script is easy to read and easy to trust. A skill with a tangle of code doing five things is the kind other people won't install, and you won't remember in a month.

Step 5: Write the description like you'll forget it

Come back to the description one more time before you call it done. Future-you, and anyone you share the skill with, decides whether to trust it from that one line. Make it match how you actually phrase requests, name the trigger situation, and avoid overclaiming. A tight description is the difference between a skill that loads when it should and one that sits unused because the agent never connects it to your ask.

A slightly bigger example

Once the instructions-only version clicks, here's what adding a script looks like. Say you want a skill that checks a URL is live before you paste it into a blog post. The agent can't fetch a URL by reasoning, so this one needs code.

The folder gets a small script, check-link.py, that takes a URL and prints the status code. The SKILL.md points at it:

---
name: link-check
description: Verify a URL returns a healthy status before using it in published content. Use when adding or reviewing external links.
---

# Link Check

When asked to verify a link, run `scripts/check-link.py <url>`.
- Status 200 means the link is safe to use.
- A 404 or timeout means flag it and suggest removing the link.
- Report the status plainly; don't guess if the script fails.

Notice the instructions still carry most of the weight. The script does one narrow thing, and the SKILL.md tells the agent when to run it and how to read the result. That split, small script plus clear instructions, is the pattern nearly every good skill follows. Resist the urge to make the script clever; a skill you can read in thirty seconds is a skill people will trust.

Iterate on real work, not imagined edge cases

The temptation after writing a skill is to bulletproof it against every scenario you can dream up. Don't. Use it on your actual work for a week and let the real gaps surface. You'll find the description misses a phrasing you use, or the instructions assume a step you skip. Those are the fixes that matter, and you only see them by using the thing. A skill polished against imaginary edge cases and never used is worth less than a rough one you run every day.

The faster path: use a meta-skill

You don't have to hand-craft every file. skill-creator is Anthropic's own skill for building skills; it scaffolds the folder, the SKILL.md, and the structure so you fill in the substance. It's the fastest way to go from idea to working skill, and a good way to learn the conventions by seeing them applied. We walk through it in skill-creator: my first custom skill.

If your skill needs to talk to an external system, mcp-builder is the companion piece, and the choice between them is worth understanding early: see skill-creator vs mcp-builder, which to learn first.

The mistakes that trip up first-timers

Three come up again and again. Making the first skill too big, so it never quite works and you give up; start with fifteen lines. Writing a vague description, so the agent never loads it; write it to match your real phrasing. Adding scripts before you need them, so the skill is harder to trust than it should be; stay instructions-only until the job forces code.

Installing skills from strangers is its own risk, since a skill runs code with your permissions. Read any SKILL.md and its scripts before you run them, and prefer sources with a public repo and recent commits. Our guide on how to audit a Claude skill before installing covers the checks.

One more thing worth saying: a skill is documentation that happens to run. The act of writing down how you format commits, or prep a release, or handle a support reply, forces you to make the fuzzy rules in your head explicit. Half the value shows up before the agent ever loads the file, because you finally wrote the process down. Teams that build a handful of shared skills end up with a living record of how they actually work.

Your first skill should take fifteen minutes and save you an hour a week forever. Pick the thing you're tired of retyping, write it down, and let the agent remember it for you.

FAQ

What exactly is a Claude Code skill? A folder with a SKILL.md file holding a name, description, and instructions, plus optional scripts. When your request matches the description, the agent loads the instructions and follows them.

Do I need to be a programmer? Not for a simple one. A skill can be pure instructions with no code, and those are genuinely useful. You add code only when the skill must run scripts.

Where do I put the folder? In a skills directory Claude Code scans, each skill in its own subfolder with a SKILL.md inside. Check the current docs for the exact path, since it varies by setup.

How is a skill different from a good prompt? A prompt is one-off. A skill is a prompt you saved, named, and taught the agent to reach for automatically, and it can bundle scripts a prompt can't.

Is it safe to install other people's skills? Treat them like code you didn't write. A skill runs scripts with your permissions, so read the SKILL.md and scripts first and prefer sources with a public repo and recent activity.