How to Create a Claude Code Skill: A Step-by-Step Guide for Beginners

A Claude Code skill is a folder that contains a single instruction file, called SKILL.md, which teaches Claude how to do one repeatable job well. That is the entire idea. When your request matches what the skill is for, Claude reads the instructions and follows them, so you get the same high-quality result every time instead of re-explaining the process from scratch.

The best way to picture it: a skill is a checklist you hand to a very capable teammate. You write down how you want a task done once - the steps, the rules, the format of the output - and from then on Claude reaches for that checklist automatically whenever the situation calls for it. You are not writing a program. You are writing instructions in plain English.

This is why skills are one of the highest-leverage things a beginner can build. You do not need to know a programming language. If you can describe how you like a task done, you can make a skill for it. In this guide we will build one together, test it, and cover when a skill is the right choice versus a slash command or an MCP server.

A skill needs exactly two things: a folder with a short, hyphenated name, and a file inside it named SKILL.md. That is the minimum viable skill. Everything else - extra reference files, scripts, examples - is optional and added only when a skill grows.

Skills live in one of two places. A personal skill goes in the .claude/skills folder inside your home directory, and it is available in every project you open. A project skill goes in a .claude/skills folder at the root of a specific project, and it travels with that project when you share it. For your first skill, personal is the simplest choice.

Pick a name for what your skill does, in lowercase with hyphens. For this walkthrough we will build a skill that writes a clean, consistent commit message, so we will call it commit-helper. Open Claude Code and ask it to make the folder for you - this is the easiest way and it works whether you are in the desktop app or the terminal.

A prompt as simple as "Create a new personal skill folder called commit-helper in my Claude skills directory and add an empty SKILL.md file inside it" will do the whole thing. Claude knows where the skills folder lives and will set it up. You never have to touch the file system by hand if you do not want to.

The body of SKILL.md is where you write the actual instructions, in plain markdown. Treat it like onboarding a new team member: be specific about the steps, the rules, and what a good result looks like. The clearer you are, the more consistent Claude will be.

For our commit-helper, the body might say: read the staged changes, summarize what changed in one short line under 60 characters, use the present tense, never invent changes that are not in the diff, and add one or two bullet points only if the change is large. Notice that these are the same instructions you would give a person. That is the whole skill.

At the very top of SKILL.md you add a small block of frontmatter between two lines of three dashes. It holds two fields: a name and a description. This block is short, but the description is the single most important line in the whole skill.

Here is why. Claude does not run your skill because you told it to by name. It reads the description of every available skill and decides, on its own, which one fits the request in front of it. A vague description means Claude will miss the moment to use your skill. A precise one means it fires at exactly the right time. Write the description as "Use when..." and name the trigger clearly.

A one-file skill is complete and shippable. But as a skill grows, you can drop extra files into the same folder - a longer reference document, a short script, an example template - and mention them in SKILL.md so Claude reads them when relevant. Claude only pulls them in when the task calls for it, which keeps the skill light.

The rule of thumb: start with just SKILL.md. Add a supporting file the first time you find yourself pasting the same long reference into the instructions. Do not build the extra files up front for a job you have not hit yet. Skills are meant to grow from real use, not from imagined future needs.

Testing a skill is simple: start a fresh Claude Code session and do the thing the skill is for. For commit-helper, make a small change to a file, stage it, and ask Claude to write the commit message. If the skill is wired correctly, Claude will follow your instructions without you naming the skill at all.

If it does not fire, do not panic - this is the normal part of the loop. Nine times out of ten the fix is the description. Sharpen it to name the exact trigger, start a new session, and test again. Once it fires reliably, you are done. You have a repeatable process that runs itself from now on.

Skills are one of three ways to extend Claude Code, and beginners often mix them up. The quick version: a skill is for a repeatable job with a real process, a slash command is for a one-shot prompt you want to trigger fast, and an MCP server is for connecting Claude to an outside tool like your calendar, your database, or GitHub.

If you are still deciding, ask one question: is this a process I repeat, or a connection to another tool? A process is a skill. A connection is an MCP server. Once you can answer that, the choice is obvious. And if you want the deeper version, our explainer on Claude skills and our guide to MCP servers both go a level further.

The real payoff of skills is not the first one - it is the tenth. Every time you catch yourself explaining the same process to Claude twice, that is a skill waiting to be written. Over a few weeks you build up a small library of them, and Claude quietly gets better at working the way you work.

Start with commit-helper today. Then make one for how you format a client email, one for how you review a pull request, one for how you draft a blog outline. None of them take more than ten minutes. That habit - noticing a repeat and turning it into a skill - is what separates people who use Claude Code from people who compound with it. Inside the Claude Code Club we share the ones that work, so you are never starting from a blank file.