Skills in Claude: What They Are and How SKILL.md Works
-
Last Updated: May 1, 2026
-
By: javahandson
-
Series
Skills in Claude: What They Are and How SKILL.md Works
Skills in Claude are one of the most useful — and most underrated — features in the entire Claude ecosystem. If you have ever noticed Claude following a specific format, sticking to exact rules, or producing perfectly structured output without you spelling everything out, chances are a Skill was involved.
Skills in Claude are a way to give Claude a custom set of instructions, rules, and context for a specific type of task. Think of a Skill as a mini-guide written by you (or your team) that Claude reads before doing certain work. These instructions live inside a special file called SKILL.md.
This article explains everything a beginner needs to know about Skills in Claude. We will cover what Skills are, why they exist, what a SKILL.md file looks like, how Claude finds and uses them, when to write your own Skill, and common mistakes to avoid. By the end, you will have a clear picture of how this feature works and how to use it effectively.
- 1. What Is a Skill in Claude?
- 2. Why Do Skills Exist? The Problem They Solve
- 3. What Is a SKILL.md File?
- 4. Where Are Skills Stored?
- 5. How Claude Reads and Uses Skills
- 6. Anatomy of a Good SKILL.md File
- 7. How to Write Your Own Skill
- 8. Using Multiple Skills Together
- 9. Common Mistakes to Avoid When Writing Skills
- 10. Conclusion
1. What Is a Skill in Claude?
A Skill in Claude is simply a set of written instructions stored in a file named SKILL.md. When Claude is working inside a project that has skills set up, it reads those SKILL.md files before carrying out certain tasks. The instructions inside tell Claude things like: what tools to use, what format to follow, what rules to apply, and what mistakes to avoid.
The word “Skill” here does not mean Claude learns something new permanently. It is not machine learning or model training. A Skill is more like a recipe card or a style guide that Claude picks up and follows for that task. Once the task is complete, Claude reverts to its default behavior unless the Skill is loaded again.
Here is a simple real-world analogy. Imagine you hire a freelance writer and hand them a brand guide — a document that explains your company’s tone, font preferences, how to structure articles, and what words to avoid. The writer reads it and follows it. That brand guide is essentially what a SKILL.md file is for Claude. It sets the rules for a specific job.
Skills are stored in a folder on the computer Claude has access to, typically under a path like /mnt/skills/. There can be multiple Skills in a project — one for writing Word documents, one for creating presentations, one for generating reports, and so on. Claude reads the relevant one before starting that type of task.
2. Why Do Skills Exist? The Problem They Solve
To understand why Skills are useful, it helps to understand the problem they solve. Claude is a very general-purpose assistant. It can write code, draft emails, create documents, build spreadsheets, and much more. But every environment where Claude runs is a little different.
For example, if you ask Claude to create a Word document, the exact way to do so depends on which library is installed, its version, your organization’s formatting rules, and the file path where you want to save the output. Claude cannot guess all of this correctly every single time based on general training alone.
Before Skills existed, the only option was to paste all these instructions into every single prompt. That was repetitive, error-prone, and easy to forget. If you forgot to include the instructions, Claude would default to general behavior and might produce output that does not match what you need.
Skills solve this by making the instructions permanent and automatic. Instead of you typing the rules every time, the SKILL.md file holds them. Claude reads the file before starting, so the instructions are always there. You write the rules once, and they apply every time that task type is triggered.
This makes Claude more consistent, more accurate for your specific environment, and much easier to work with over time. It is one of the features that makes Claude genuinely useful for professional and production workflows rather than just casual conversations.
3. What Is a SKILL.md File?
A SKILL.md file is a plain text file written in Markdown format. Markdown is a simple way of formatting text using symbols like # for headings, ** for bold, and – for bullet points. The .md extension stands for Markdown. The file is named SKILL.md by convention.
Each SKILL.md file starts with a small block called front matter, which is enclosed between two sets of triple dashes (—). This front matter contains the skill name and a description. The description is very important — it tells Claude when this Skill is relevant. Claude reads the description to decide whether to load the Skill for a given task.
After the front matter comes the actual content of the Skill: the instructions, rules, examples, code patterns, and anything else Claude needs to know for that type of task. This content is just regular Markdown text — headings, paragraphs, bullet points, and code blocks.
Here is what a simple SKILL.md file looks like:
---
name: docx
description: "Use this skill when creating or editing Word documents (.docx).
Triggers include requests for reports, letters, and formal docs."
---
# Word Document Creation
## Overview
Always use the docx npm library to create Word documents.
## Page Size
- Always set page size explicitly: width 12240, height 15840 (US Letter)
- Use 1 inch margins on all sides (1440 DXA units)
## Fonts
- Default font: Arial, size 22 (11pt)
- Headings: Arial Bold
## Critical Rules
- Never use unicode bullet characters directly
- Always use LevelFormat.BULLET with a numbering config
- After creating the file, validate it with the validation script
This example is a simplified version of a real docx skill. It tells Claude exactly which library to use, which page size to set, which fonts to apply, and which common mistakes to avoid. Without this file, Claude might guess some of these correctly, but not all of them — and small mistakes in document generation can render the file invalid or make it look wrong.
| 💡 Key point: SKILL.md is not code. It is plain English (or Markdown) instructions. You do not need to be a programmer to write a SKILL.md file. If you can write a clear list of instructions, you can write a Skill. |
4. Where Are Skills Stored?
Skills are stored as files on the computer Claude has access to during a session. In most Claude setups with computer use enabled, there is a dedicated folder structure for Skills. Understanding this folder structure helps you know which Skills are available and how to add your own.
4.1 The Skills Folder Structure
The root Skills folder is typically located at /mnt/skills/. Inside this folder, there are usually two main subfolders:
a. /mnt/skills/public/ — This contains Skills provided by default, such as creating Word documents, PDFs, Excel files, PowerPoint presentations, and more. These are read-only. You cannot edit them.
b. /mnt/skills/user/ — This is where your own custom Skills live. You create files here when you want to teach Claude how to handle a specific type of task in your own way.
Inside each subfolder, Skills are organized by name. Each Skill gets its own subfolder, and inside that subfolder is the SKILL.md file. For example:
/mnt/skills/
public/
docx/
SKILL.md ← skill for creating Word documents
pdf/
SKILL.md ← skill for PDF operations
pptx/
SKILL.md ← skill for PowerPoint presentations
xlsx/
SKILL.md ← skill for Excel spreadsheets
user/
article-writer/
SKILL.md ← your custom skill for writing articles
4.2 Public vs User Skills
Public Skills covers common document and file types. They are pre-written, tested, and ready to use. You do not need to do anything to use them — Claude automatically checks if a public skill is relevant before doing certain tasks.
User Skills are entirely yours. You write them for tasks that are specific to your workflow, your organization’s standards, or your personal preferences. For example, you might write a user skill for generating invoices in a specific format, writing articles in your blog’s style, or creating database migration scripts that follow your team’s naming conventions.
| Public Skills | User Skills |
| Pre-built by default | Created by you |
| Read-only — cannot be edited | Fully editable — you own them |
| Cover common file types (docx, pdf, pptx, xlsx) | Cover your specific workflows |
| Loaded automatically when relevant | Loaded when Claude detects the task matches the description |
5. How Claude Reads and Uses Skills
This is the most important part to understand. Claude does not automatically read every SKILL.md file in existence before every task. That would be slow and unnecessary. Instead, Claude uses a specific process to decide which Skills are relevant and loads only those.
5.1 The Skill Matching Step
When you give Claude a task, Claude first looks at the available Skills list. This is essentially a directory of all SKILL.md files on the system. Claude scans the name and description of each Skill. The description is the key part — it tells Claude what kinds of tasks this Skill is meant for.
For example, a Skill with this description:
"Use this skill whenever creating or editing Word documents (.docx files). Triggers include: any mention of 'Word doc', 'report', '.docx', or requests to produce formal documents."
…will be matched when you say things like “create a Word report”, “write me a .docx file”, or “make a formal document I can download.” Claude reads the description, compares it to your request, and decides: yes, this Skill is relevant for this task.
5.2 The View Step — Claude Actually Reads the File
Once Claude decides a Skill is relevant, it calls the view tool on the SKILL.md file. This is how Claude reads the file’s actual content. The view tool opens the file and puts its contents into Claude’s context — the working memory Claude uses during a conversation.
This step is critical and, importantly, it is mandatory. Claude is instructed never to skip reading the SKILL.md before doing the task the Skill covers. The reason for this rule is simple: the SKILL.md contains environment-specific details — which library version is installed, which file paths to use, and which quirks to watch out for — that are not part of Claude’s general training. Skipping the Skill means lower-quality output.
5.3 Following the Instructions
After reading the SKILL.md, Claude follows the instructions inside it while carrying out your task. If the Skill says “always set page margins to 1440 DXA”, Claude does that. If it says “never use Unicode bullet characters”, Claude avoids them. If it lists a validation step, Claude runs it.
The result is that your output consistently follows the rules in the SKILL.md without you having to repeat them in every prompt. This is the core value of Skills: write the rules once, benefit every time.
| 🔍 In practice: If you look at Claude’s responses when it creates a Word document or PDF, you might notice it says something like ‘Reading the docx skill first…’ before it writes any code. That is the view step happening. Claude is loading the SKILL.md before starting the task. |
6. Anatomy of a Good SKILL.md File
Now that you know what a SKILL.md does and how it is used, let us look at what makes a good one. Writing a clear, well-structured SKILL.md is the key to getting consistent, high-quality output from Claude.
6.1 Front Matter — Name and Description
Every SKILL.md must start with front matter. The two required fields are name and description. The name is just a label. The description is far more important — it must clearly describe when this Skill should be used. If the description is vague or too narrow, Claude might not load the Skill when it should.
---
name: invoice-generator
description: "Use this skill when the user asks to create, generate,
or produce an invoice, billing document, or payment receipt.
Triggers include the words invoice, billing, receipt, payment doc."
---
Notice how the description lists specific trigger words. This helps Claude’s matching logic recognize when to load this Skill. A description like “for invoices” is too short. A description that lists common trigger words and phrases is much better.
6.2 Overview Section
After the front matter, start with a short overview. This gives Claude the big picture: what this Skill is for and the most important rule. Keep it to two or three sentences.
# Invoice Generator Skill ## Overview Use this skill when creating invoice documents in PDF or DOCX format. Always use the invoice template stored at /mnt/templates/invoice_template.html. Final files must be saved to /mnt/user-data/outputs/.
6.3 Rules and Requirements
This is the main body of the Skill. List all the rules Claude must follow for this task. Be specific. Vague instructions like “make it look nice” do not help. Specific instructions, such as “always use Arial font at 11pt for body text,” are much more useful.
## Rules - Company name must appear in bold at the top of every invoice - Date format must always be DD/MM/YYYY - Tax calculation: multiply subtotal by 0.18 for GST - Total must be shown in Indian Rupees (INR) with the ₹ symbol - Footer must include: "Thank you for your business | support@company.com"
6.4 Critical Warnings
If there are specific mistakes Claude commonly makes for this task, call them out explicitly in a clearly labeled section. This saves a lot of debugging time.
## Critical Rules — Do NOT - Do NOT use $ symbol — always use ₹ - Do NOT skip the validation step after creating the file - Do NOT use percentage-based widths in tables — they break in Google Docs - Do NOT create separate CSS files — always inline all styles
6.5 Examples (Optional but Highly Recommended)
If you can include a short example of the desired output format — even just a few lines — do it. Examples are often clearer than written rules. Claude can pattern-match from an example very effectively.
7. How to Write Your Own Skill
Writing your first Skill can feel a little intimidating, but it is actually quite straightforward. You just need to observe what Claude does, identify what it keeps getting wrong or is inconsistent about, and write those corrections into a SKILL.md file.
7.1 Step-by-Step Process
a. Identify the task. Pick one specific, repeatable task you ask Claude to do regularly. For example: ‘Write a blog post in my style’ or ‘Create a weekly status report’.
b. List what Claude currently gets wrong. Ask Claude to do the task a few times. Write down every time it does something you did not want — wrong format, wrong font, missing section, wrong file path.
c. Write the rules. Turn your list of corrections into clear, simple instructions. Keep each rule on one line. Use plain English.
d. Write the description carefully. The description in the front matter is what Claude uses to decide whether to load your Skill. Make it specific to the phrases you actually use when asking for this task.
e. Save the file. Create the folder /mnt/skills/user/your-skill-name/ and save your instructions as SKILL.md inside it.
f. Test it. Ask Claude to do the task. Observe whether it reads your Skill (it should mention viewing the file). Check if the output follows your rules. Refine and repeat.
7.2 A Real Example — Java Unit Test Generator Skill
Let us walk through a concrete example that Java developers will relate to directly. Suppose your team uses JUnit 5 and Mockito, and you frequently ask Claude to write unit tests for your service classes. Without a Skill, Claude might use JUnit 4 annotations, pick the wrong mocking style, or skip edge cases your team always wants covered.
Here is what a user-written Skill for Java unit test generation would look like:
---
name: java-unit-test-generator
description: "Use this skill when the user asks to write, generate, or create
unit tests, test cases, or JUnit tests for Java classes or methods.
Triggers: write unit tests, generate tests, add test coverage,
write JUnit test, test this class, write test cases for."
---
# Java Unit Test Generator Skill
## Overview
Generate clean, production-ready JUnit 5 unit tests for Java service and
repository classes. Always use JUnit 5 (Jupiter) and Mockito. Never use
JUnit 4 annotations under any circumstances.
## Dependencies Assumed (already in pom.xml)
- junit-jupiter 5.10+
- mockito-core 5.x
- mockito-junit-jupiter 5.x
- assertj-core 3.x (preferred over raw JUnit assertions)
## Test Class Structure
- Class name: <ClassName>Test (e.g., OrderServiceTest)
- Package: same package as the class under test
- Annotate class with: @ExtendWith(MockitoExtension.class)
- One test method per behaviour — not per method
## Annotations to Use
- @ExtendWith(MockitoExtension.class) — on the test class
- @Mock — for dependencies
- @InjectMocks — for the class under test
- @Test — on every test method
- @DisplayName("...") — always add a human-readable name
- @BeforeEach — for shared setup logic
## Naming Convention for Test Methods
Use this pattern: methodName_stateUnderTest_expectedBehavior
Examples:
placeOrder_whenStockAvailable_shouldReturnConfirmation()
placeOrder_whenStockEmpty_shouldThrowOutOfStockException()
calculateDiscount_whenUserIsVip_shouldApplyTwentyPercent()
## Assertion Style
- Always use AssertJ: assertThat(result).isEqualTo(expected)
- For exceptions: assertThatThrownBy(() -> ...).isInstanceOf(...)
- Never use assertTrue(result == expected) — too vague
## What to Cover in Every Test Class
- Happy path (normal successful execution)
- Null input handling
- Boundary values (zero, empty list, max value)
- Exception scenarios (what throws and when)
- Verify mock interactions with verify() where relevant
## Critical Rules — Do NOT
- Do NOT use @RunWith — that is JUnit 4. Use @ExtendWith instead.
- Do NOT use Mockito.mock() inline — always use @Mock annotation
- Do NOT write a single test that checks multiple unrelated behaviours
- Do NOT use raw assertEquals — use AssertJ assertThat()
- Do NOT leave test methods without a @DisplayName
Look at how specific every rule is. The Skill tells Claude which JUnit version to use, exactly how to name test methods, which assertion library to prefer, what scenarios to cover, and a dedicated section of things Claude must never do. This level of detail is what makes a Skill genuinely useful in a professional Java project.
With this Skill in place, every time you say ‘write unit tests for this OrderService class’, Claude automatically loads the Skill, follows your team’s conventions, uses the right annotations, and produces tests that are ready to drop into your codebase — no cleanup needed.
8. Using Multiple Skills Together
One of the more powerful features of the Skills system is that multiple Skills can be relevant for a single task, and Claude can read more than one SKILL.md before starting. This is called combining Skills.
For example, suppose you ask Claude: “Write a blog article about Java streams and save it as a Word document.” Two Skills are relevant here:
- The article-writer Skill, which tells Claude how to structure and write the article.
- The docx Skill — which tells Claude how to create a valid, properly formatted .docx file.
Claude reads both Skills before starting. The article-writer’s skill shapes the content. The docx Skill shapes the technical implementation of the Word file. The result is content that follows your writing rules AND a correctly generated file.
This composability is by design. Claude is instructed to scan all available Skills and read every one that seems relevant, not just the first match. So when you build out a library of Skills over time, they work together naturally without you having to do anything extra.
| 💡 Tip for Power Users: As your Skills library grows, keep each Skill focused on one specific task. A narrow, focused Skill with a clear description is easier for Claude to match correctly than a broad Skill that tries to cover everything. Combine multiple focused Skills rather than writing one giant Skill. |
9. Common Mistakes to Avoid When Writing Skills
Skills are simple to write, but a few common mistakes can make them less effective. Knowing this up front will save you time.
9.1 Vague Description
The description field is what Claude uses to decide whether to load your Skill. If your description is too vague — for example, just “for writing tasks” — Claude might not load it when it should, or might load it when it is not needed.
Bad description: “Use for writing tasks.”
Good description: “Use when the user asks to write, draft, or create a blog article, tutorial, how-to guide, or technical post. Triggers: write an article, draft a post, create a guide.”
9.2 Rules That Are Too Vague
Rules like “make it professional” or “use good formatting” do not give Claude anything concrete to act on. Claude needs specific, measurable instructions.
Bad rule: “Make the document look professional.”
Good rule: “Use Arial font at 11pt for body text. Use 1-inch margins on all sides. Include a page number in the footer.”
9.3 Forgetting to List What NOT to Do
Claude has default behaviors that can conflict with your rules. If you do not explicitly say “do not do X”, Claude might do X anyway because it seems like a reasonable default. The most effective SKILL.md files include a clear “Do NOT” section.
9.4 Putting Too Much in One Skill
If your SKILL.md becomes very long and covers many unrelated topics, it becomes harder for Claude to extract the relevant rules at the right time. Keep each Skill focused on one task category. If you find yourself writing a Skill that covers articles, invoices, and reports, split it into three separate Skills.
9.5 Forgetting to Test
After writing a Skill, always test it. Ask Claude to perform the task and observe whether it loads the Skill and whether the output adheres to your rules. It is common to need two or three rounds of editing before a Skill is exactly right.
10. Conclusion
Claude’s skills are a practical, powerful way to make Claude behave consistently on specific tasks without repeating instructions in every prompt. A Skill is simply a SKILL.md file — plain text written in Markdown — that contains rules, formatting guidelines, and task-specific instructions. Claude reads the relevant SKILL.md before starting a task and follows its contents.
The system is built around a simple flow: Claude scans the descriptions of available Skills, loads the relevant ones using the view tool, and applies the instructions to carry out your request. Skills can be combined — multiple Skills can apply to a single task — and you can write your own user Skills for any workflow that matters to you.
For beginners, the most important things to remember are: the description field is how Claude finds your Skill, specific rules work far better than vague ones, and a “Do NOT” section prevents Claude’s default behaviors from overriding your rules. Start small, test frequently, and refine as you go.
Once you have a few well-written Skills in place, you will notice that working with Claude becomes faster, more consistent, and more reliable. You stop repeating yourself. Claude stops guessing. And the output starts matching exactly what you need every single time.