How to Create an Agent Skill: A Step-by-Step Guide
Published on Reading time: 9 min
- #claude-skills
- #agent-skills
Contents
If you have ever wished Claude already knew how your team writes commit messages, formats reports, or names files, an agent skill is the answer. A skill is a small folder of instructions you write once, and from then on Claude pulls it in automatically whenever the task matches. No plugin store, no code compilation, no API keys.
The good news is that creating one is far simpler than it sounds. You do not need to be a programmer. If you can write a clear set of notes for a new coworker and save a text file, you already have everything it takes. This guide walks you through how to create an agent skill from the empty folder to a working, shareable result, with a real example you can copy.
What Is an Agent Skill, Exactly?
An agent skill is a folder containing a SKILL.md file that teaches an AI agent how to perform a specific task, which the agent loads on demand only when it is relevant. Think of it as a reusable playbook. Instead of re-explaining the same procedure in every conversation, you write it down once and the agent reaches for it automatically.
What makes skills clever is that they are progressively loaded. The agent does not read every skill in full all the time, which would waste its limited working memory. It only sees a short list of skill names and descriptions, and pulls the full instructions into context the moment your request matches one. That keeps the agent fast and focused.
Skills are one of three ways to extend Claude, and it helps to know where they fit. If you want a clear comparison, see our breakdown of Claude skills vs MCP vs subagents. In short: skills add know-how (instructions and procedures), MCP servers add connections to outside tools and data, and subagents add parallel workers. This guide is about the first one.
What You Need Before You Start
To create your first agent skill you only need a recent version of Claude Code (or another agent that supports the skills standard), a plain text editor, and a clear idea of one repetitive task you want to automate. That is the whole list.
A few specifics worth checking:
- An agent that supports skills. Claude Code reads skills, as does the Claude desktop app and the API. If you have not set it up yet, follow our guide to install Claude Code.
- A text editor. Skills are just text files. Any editor works — the built-in one in your code tool, VS Code, or even a basic notepad app.
- One real task. The best first skill solves a problem you actually hit. “Write our changelog entries in this format” beats an abstract “be more helpful.” Specific tasks make for specific, reliable skills.
You do not need to know how to code. Many useful skills contain no scripts at all — just well-written instructions. If you are completely new to working in a terminal-style tool, our guide on Claude Code for non-coders will get you comfortable first.
The Structure of a Skill
A skill is a folder named after the skill, containing a required SKILL.md file and optional scripts/, references/, and assets/ subfolders for code, background material, and templates. Only the SKILL.md is mandatory; everything else is there when you need more depth.
Here is what a fuller skill folder looks like:
commit-helper/
├── SKILL.md # required: metadata + instructions
├── references/ # optional: extra docs loaded only when needed
│ └── examples.md
├── scripts/ # optional: helper scripts the agent can run
│ └── format.py
└── assets/ # optional: templates, config files, images
└── template.txtThe subfolders matter because of that progressive-loading idea. You keep SKILL.md short and put rarely-needed detail in references/, so the agent loads the heavy material only when the task truly calls for it. For a small first skill, ignore the extra folders entirely — a single SKILL.md is a complete, valid skill.
Where you place the folder decides who can use it. A personal skill usually lives in your user-level skills directory so it follows you everywhere; a project skill lives inside the project repo so your whole team shares it. The exact paths can change between releases, so confirm them in the official Claude Code docs rather than trusting any single tutorial.
Writing a SKILL.md (With a Real Example)
The SKILL.md file has two parts: a YAML frontmatter block at the top holding the required name and description fields, and a markdown body below it containing your actual instructions for the agent. Get the frontmatter right and the rest is just clear writing.
Let’s build a real one. Say you want Claude to write your Git commit messages in a consistent style. Create a folder called commit-helper, and inside it a file called SKILL.md with this content:
---
name: commit-helper
description: Writes Git commit messages in the Conventional
Commits format. Use when the user asks to commit changes,
write a commit message, or describe a code change.
---
# Commit Helper
## Your instructions
When the user asks you to write a commit message, follow
the Conventional Commits format exactly.
## Task
1. Run `git diff --staged` to see what changed.
2. Pick the right type: feat, fix, docs, refactor, test,
or chore.
3. Write a one-line summary under 50 characters in the
form `type: short description`.
4. If the change is non-trivial, add a blank line and a
short body explaining *why* the change was made.
5. Never invent changes that are not in the diff.That is a complete, working skill. Two things make it succeed:
- The
descriptionis the trigger. The agent decides whether to load your skill based almost entirely on this field. Write it from the user’s point of view — name the situations where it should fire (“Use when the user asks to commit changes…”). A vague description means the skill never activates. - The body reads like instructions to a careful assistant. Number the steps, state the rules plainly, and include guardrails (“Never invent changes”). The clearer your instructions, the more reliable the result.
Your Instructions and the Task Section
You can structure the body however you like, but two headings carry most of the weight. Use an instructions section for the rules and tone — the standing principles the agent should always follow. Use a task section for the concrete, ordered steps to carry out the job. Separating the “always-true rules” from the “step-by-step procedure” keeps the agent from blurring them together and skipping steps under pressure.
If your procedure needs long examples or reference tables, do not dump them into SKILL.md. Put them in references/examples.md and point to the file from the body (“See references/examples.md for sample messages”). The agent will open it only when needed.
Testing and Improving Your Skill
Test a new skill by starting a fresh agent session and giving it a plain-language request that should trigger the skill, then watching whether the agent loads it and follows your instructions correctly. If it fires and behaves, you are done; if not, the fix is almost always in the description.
A practical testing loop:
- Restart the agent so it picks up the new skill folder.
- Make a natural request — “write a commit message for my staged changes.” Do not name the skill; the whole point is that the agent finds it on its own.
- Check that it loaded. Most agents will indicate when a skill activates. If it ignored the skill entirely, your
descriptionprobably does not match the way you phrased the request — add the words and situations a user would actually say. - Check the output. If it loaded but skipped a step, tighten that step in the body or move it earlier.
Improving a skill is iterative, and that is normal. The strongest skills are built incrementally: run the agent on real tasks, notice exactly where it stumbles, and add a line that closes that gap. Resist the urge to make one giant skill that does everything — narrow, single-purpose skills are easier to trigger correctly and easier to debug. This loop of observe-and-refine is the same mindset behind loop engineering, and it is the difference between a skill that “kind of works” and one you trust.
For more polished, ready-to-study patterns, browse our collection of Claude skills examples to see how well-written descriptions and bodies are structured.
Sharing Your Skill
Because a skill is just a folder of text files, you share it by committing it to a project repository, zipping the folder, or publishing it to a skills marketplace — anyone who adds it to their own skills directory can use it immediately. There is nothing to install or compile.
Three common ways to share:
- Inside a project. Commit the skill folder into your project repo. Now every teammate who works in that project automatically gets the skill — no setup on their end. This is the best option for team conventions.
- As a standalone bundle. Zip the folder and send it. The recipient drops it into their personal skills directory and it is live.
- Through a marketplace. A growing ecosystem lets you find and distribute skills publicly. See our overview of the agent skills marketplace for where these live and how distribution works.
One caution before you share widely: skills can include scripts the agent may run, so treat a downloaded skill the way you would treat any downloaded code. Read the SKILL.md and any files in scripts/ before trusting them. The same care that applies to MCP security applies here — review before you run.
FAQ
What is the difference between an agent skill and an MCP server?
A skill teaches the agent how to do something using plain instructions and optional files, while an MCP server gives the agent new connections to external tools, databases, or APIs. Skills are knowledge; MCP is plumbing. Many real workflows use both — a skill that describes a procedure and an MCP server that reaches the data the procedure needs.
Do I need to know how to code to create a skill?
No. The most basic and often most useful skills contain nothing but written instructions in a SKILL.md file. Coding only becomes relevant if you want the skill to bundle helper scripts in a scripts/ folder, and even then the agent runs them — you mostly just supply them. If you can write clear step-by-step notes, you can write a skill.
How does the agent decide when to use a skill?
The agent reads only the name and description of every available skill, and loads the full instructions when your request matches a description. This is why the description field is the single most important part of the file. Write it to name the concrete situations and phrases a user would use, not an abstract summary of what the skill does.
Where do I put the skill folder?
Personal skills go in your user-level skills directory so they follow you across every project, while project skills live inside the project repository so your whole team shares them. The exact directory paths can differ by tool and version, so always confirm the current locations in the official Claude Code documentation before you start.
How is a skill different from a subagent?
A skill adds reusable know-how to the agent you are already talking to, whereas a subagent is a separate worker the main agent can delegate an isolated task to. Use a skill when you want to standardize how a job is done; use a subagent when you want to run work in parallel or keep a task’s context separate. They complement each other and are often combined in multi-agent systems.
Conclusion
Creating an agent skill comes down to three moves: make a folder, write a SKILL.md with a sharp description and clear instructions, then test it with a natural request and refine. Start with one small, real task — the commit helper above is a perfect first project — and resist the temptation to build something sprawling. A narrow skill that fires reliably beats a broad one that rarely triggers.
From there, the path forward is to build a small library. Add a second skill for the next repetitive task, then a third, and soon the agent handles your routine work the way you would, without being re-told each time. If you want to go deeper on the tool itself, our Claude Code tutorial and Claude Code workflows guides show how skills fit into a full day’s work — and for the canonical reference, keep the official docs close while you build.
