A skills file is a short document named SKILL.md that tells Claude how you want a specific task done, once, so you stop re-explaining it every time. It has a short header with a name and a description of when to use it, and a body with the steps you want followed. If you can write instructions for a new hire, you can write one. The format is documented by Anthropic and uses the same basic structure across Claude Code, the Claude API, and claude.ai, though each surface has its own setup. The four parts that make a good one are a clear description, a one-paragraph statement of the job, the steps in order, and a short list of guardrails.
You have probably had this experience. You ask Claude to do something, it does a decent job, and the next day you ask for the same thing and the result comes back a little different from how you actually want it.
A skills file fixes that. It is a short document that tells Claude how you want a specific task done, once, so you stop re-explaining it every time. If you can write instructions for a new hire, you can write one. This is a practical entry point into The 7 Levels of AI Proficiency, and it is more approachable than it sounds.
Here is what a skills file is, when it is worth writing one, and how to build your first one in about fifteen minutes. There is a starter file you can download near the bottom and fill in today.
What a skills file actually is
A skills file is a plain text file named SKILL.md. It has two parts: a short header and a body of instructions. The header (Anthropic calls it the frontmatter) carries a name and a description, and the description is the part Claude leans on to decide when to use the skill. The body is where you write, in your own words, how the task should be done.
When you give Claude a set of skills, it reads the descriptions and pulls in the right one at the right moment, based on what you are asking for. You write the instructions once. Claude can load them when the task comes up, and you can invoke the skill directly when you want to be sure. That is the whole idea.
The format is documented by Anthropic as part of its Agent Skills feature, and the same basic SKILL.md structure is used across Claude Code, the Claude API, and claude.ai, though each surface has its own setup steps. The mechanics are simple on purpose.
One thing worth knowing early: the SKILL.md format is an open standard that reaches well beyond Claude. The same file also works in other AI tools, including OpenAI's Codex, Cursor, and Gemini CLI. Each tool has its own way of installing it, but the file you write is the same. You write the skill once, and it travels with you across tools.
When it is worth writing one
Not every request needs a skills file. A one-off question does not. The test is repetition. If you find yourself explaining the same preferences to Claude more than two or three times, that task is a candidate.
Good first candidates tend to look like this:
- A weekly report you format the same way every time
- Cleaning up rough meeting notes into a standard shape
- Drafting a certain kind of email in your voice
- Turning raw data into the summary your boss expects
The pattern is a task with a shape you already know. You are not teaching Claude something new. You are writing down the version you already keep in your head.
The four parts of a good skills file
Every skills file worth keeping has the same four parts. Get these right and the rest takes care of itself.
The description (this is the part people rush).
The description tells Claude when to use the skill. Write the words you would actually type. "Use when I paste raw meeting notes and want a clean status update" is a strong description. "Helps with notes" is not, because it could mean anything. Spend the most time here. A vague description is the single most common reason a skill never loads when you expect it to.
What it does, in one paragraph.
Open the body with a plain statement of the job and what a finished result looks like. If you cannot describe "done" in a sentence or two, the task is still fuzzy in your own mind, and the skill will be fuzzy too.
The steps, in order.
Write the task as numbered steps, one idea per step, the way you would walk a new hire through it. Write instructions rather than descriptions. "Pull out every decision and list it first" beats "the output should contain decisions." Order counts, so put the steps in the sequence you actually work in.
The guardrails.
Name the non-negotiables: what must always happen and what must never happen. Examples: never add a date the notes do not contain; keep the whole thing under 200 words. This is the part that protects you from the small, confident errors that are easy to miss on a busy day.
Write your first one in fifteen minutes
You do not have to start from a blank page. The fastest way in is to let Claude help you draft it from a task you already do. Paste this into Claude, then fill in the blank:
I want to turn a task I do often into a reusable skill file for you. The task is: [describe the task in one or two sentences]. Ask me up to five questions to understand: 1. when this skill should be used, 2. what the finished output should look like, 3. what steps should always be followed, 4. what should never happen, 5. and what examples or preferences are most important to me. Then write a short SKILL.md file with YAML frontmatter and a body. The frontmatter should include a name and a description. The description should clearly say when to use the skill, in plain language I would actually type. The body should include four sections: what it does, when to use it, the steps to follow, and the rules and guardrails. Keep it short, concrete, and practical. Do not overbuild it.
Claude will interview you, then hand back a draft. Read it once and tighten the description and the guardrails, because those are the two parts you know better than it does. Then save the result as SKILL.md.
Once you have a draft, test it on a real example before you trust it. This prompt checks it under pressure:
Here is a skill file I wrote: [paste it]. Here is a real example to run it on: [paste a real input]. Run the example using the skill as closely as possible. Then tell me: 1. where the instructions were clear, 2. where the instructions were unclear, 3. where you had to guess, 4. what risk or failure mode you noticed, 5. and what one change would make the skill more reliable next time. After that, rewrite the SKILL.md with only the necessary improvements. Keep it short and practical.
The answer shows you the soft spots in your own instructions and hands back a tightened version. Fold those changes into the file, and you have a skill that holds up.
A starter file to fill in today
This is the same four-part template, written out and ready to edit. Download it, rename it to SKILL.md, fill in the blanks, and delete the guidance notes as you go. It includes one fully worked example so you can see the finished shape.
Skills File Starter Template
A ready-to-edit SKILL.md with guidance and a worked example. Plain markdown, no signup.
Three mistakes worth skipping
A few patterns trip up almost everyone on their first try. You can step around them.
The first is a thin description. If the skill never seems to load when you want it, the description is almost always the reason. Rewrite it as the literal phrase you would type.
The second is writing a novel. A skill should read like a set of instructions rather than an essay. If yours runs past a single screen, you are probably explaining things Claude already knows. Cut it back to the parts that are specific to you.
The third is skipping the guardrails. The "never do this" lines feel optional until the day a small wrong number slips through. Write them first, before the steps.
Where this fits into the bigger picture
Writing a skills file is a small act with a large return. You are doing something more durable than getting one good answer. You are building a system that does the task your way, repeatedly, without you in the loop each time. That habit, capturing how a task should be done so a tool can run it reliably, is the same thinking that separates people who use AI from people who build with it.
That is exactly the progression The 7 Levels of AI Proficiency describes, and your first skills file is a real step along it. Start with one task you repeat every week. Write the four parts. Test it once. You will have built something you keep using long after the novelty wears off.
If you want to see where you stand and what to practice next, the free 7 Levels of AI Proficiency assessment places you on the levels in about ten minutes and gives you a written next step.
Related reading: How Do I Write a Good AI Prompt? A 2026 Guide (the prompting companion to this one). How Do I Start Using AI at Work? A 2026 Beginner's Guide (where to begin if AI is still new).
Sources
- Anthropic. "Agent Skills." Claude API Documentation. Accessed June 3, 2026.
- Anthropic. "Extend Claude with skills." Claude Code Documentation. Accessed June 3, 2026.
- Anthropic. "Equipping agents for the real world with Agent Skills." Anthropic Engineering Blog, October 16, 2025.
- The 7 Levels of AI Proficiency assessment.
Frequently Asked Questions
What is a skills file for Claude?
A skills file is a plain text file named SKILL.md that tells Claude how you want a specific task done. It has two parts: a short header (the frontmatter) with a name and a description that says when to use it, and a body of instructions written in your own words. You write it once, and Claude pulls it in and follows it whenever that task comes up, so you stop re-explaining your preferences every time. Anthropic documents the format as part of its Agent Skills feature, and the same SKILL.md format is used across Claude Code, the Claude API, and claude.ai, with setup steps that differ by surface.
Do I need to know how to code to write a skills file?
No. A skills file is plain writing rather than code. If you can write clear instructions for a new hire, you can write one. The whole file is a name, a description of when to use it, a few steps in order, and a short list of guardrails. Anthropic itself describes a skill as being organized like an onboarding guide you would create for a new team member.
What is the difference between a skill and a prompt?
A prompt is a one-off instruction for a single task in a single conversation. A skill is reusable: you write the instructions once and Claude loads them automatically whenever a matching request comes up, across conversations, without you pasting them in again. Prompts are for the moment. Skills are for the tasks you repeat.
Where do skills files work?
Custom skills work across Claude's products. In Claude Code you create them as a folder with a SKILL.md file. In claude.ai you can upload your own skills through Settings on the Pro, Max, Team, and Enterprise plans. Through the Claude API you upload them with the Skills endpoints. The same four-part SKILL.md format is used everywhere, though a skill uploaded to one surface does not automatically sync to the others.
Do skills files only work with Claude?
No. The SKILL.md format started at Anthropic but is now an open standard, so the same skills file works across many AI tools, including OpenAI's Codex, Cursor, Gemini CLI, and GitHub Copilot, alongside Claude Code, the Claude API, and claude.ai. Each tool has its own way of installing or placing the file, and some add their own features on top, but the core SKILL.md you write (a name, a description of when to use it, and the instructions) is the same everywhere. You write it once and reuse it.
How long should a skills file be?
Short. A skill is a set of instructions, and if yours runs past a single screen you are probably explaining things Claude already knows. Keep it to the parts that are specific to you: the description, a one-paragraph statement of the job, the steps in order, and the guardrails. The name has a 64-character limit and the description a 1024-character limit, but in practice the best skills are far shorter than that.
Find your AI Proficiency level
The free 7 Levels of AI Proficiency assessment places you across seven stages of AI capability. Under ten minutes. Research-backed scoring.