Create your own Claude skill: a step-by-step guide with SKILL.md
At its core, a skill is nothing more than a folder with a single text file that teaches Claude how a specific task runs in your company, written down once instead of explained again every time. If you already work with Claude Code or Claude Cowork but have not built a skill of your own yet, you are giving away exactly the kind of repetition that is easiest to automate. This guide shows step by step how your own SKILL.md comes together, which fields are required and where most first attempts fail.
English edition of an article from our German magazine. Read the German original
Exact measurements before the first cut. A SKILL.md needs the same precision: define the steps cleanly first, and the execution takes care of itself. Photo: www.kaboompics.com on Pexels
.claude/commands/ have been merged into skills. Both points, plus the frontmatter trap when uploading, have their own sections further down.name and description plus instructions in plain language. Claude first loads only the short description of every installed skill and reads the full content only when a request matches, so any number of skills can sit ready without extra cost. You create a skill as a zip upload in claude.ai, as a folder in Claude Code, as part of a plugin or through the Skills API, depending on who is meant to use it. Since its release as an open standard, other agents read the same format too, as long as the YAML header sticks to the six fields of the specification. What decides success is the description, because it is the only thing Claude uses to recognize when the skill should apply, and a clean before-and-after test in a fresh session shows whether it really does.Contents · 12 sections
What a SKILL.md actually is
A skill consists of a folder that contains at least one file: SKILL.md. The folder name later becomes the command you use to call the skill directly. The file itself has two parts: a YAML header with the metadata between two lines of three hyphens, and below it plain Markdown text with the actual instructions.
---
name: quote-follow-up
description: Writes a polite follow-up email for an open quote. Use this when a reminder is needed after a quote has gone unanswered.
---
## Steps
1. Ask for the company name, contact person and date of the quote if they are not known.
2. Write a short, friendly follow-up email in English, 120 words at most.
3. Offer a concrete next step, for example a short call back.That alone is a complete, working skill. No code, no installation, no programming skills, just a text file built exactly like a short onboarding for a new employee: what to do, in which order, and how to recognize the task. If you are new to Claude itself, start with our article What is Claude? (in German).
How Claude loads a skill without wasting context
The reason you can create any number of skills without every request getting slower or more expensive is a staged loading process. Anthropic calls the principle progressive disclosure, and it works in three stages:
At startup, Claude loads only the name and description from the YAML header of each installed skill, a tiny snippet of text per skill. Only when a request matches the description does Claude read the full text of the SKILL.md. If the instructions also point to further files, such as a template or a script, Claude opens those only when they are actually needed. A skill with an extensive reference file therefore costs nothing as long as nobody asks for it.
Not every token in your Skill has an immediate cost. […] Only add context Claude doesn’t already have.
Anthropic, Skill authoring best practices, 2026
In practice this means the description is the only text Claude keeps in mind for every single request. Everything else can be detailed, as long as the description manages to hit the right moment.
Where your own skill can live
Before you write the first line, it pays to decide where the skill should live at all, because the routes are completely separate and do not sync with each other.
claude.ai: In Settings you can upload your own skill as a zip file, available for Pro, Max, Team and Enterprise accounts with code execution switched on. The skill then belongs to your own account only; an admin cannot distribute it centrally to the whole team.
Claude Code: Here a folder with a SKILL.md file is enough, no upload needed. Under ~/.claude/skills/ a skill is available for all your own projects; under .claude/skills/ inside a project it applies only there and can be shared with the team through the project repository.
Claude API: Uploaded through the Skills endpoints, a skill is available to the whole workspace, that is, to every colleague who uses the same API access. That is the right route if a skill is to be built into your own application, for example together with the cost models from our article Calculating Claude API costs (in German).
Claude Code plugin: Since the plugin mechanism in Claude Code can bring skills along, there is a fourth place. A skill under <plugin>/skills/<name>/SKILL.md applies wherever the plugin is enabled and carries its own namespace in the form plugin-name:skill-name. For a team that rolls out half a dozen skills together and wants to keep them current, this is the cleanest route, because it rules out name collisions with personal skills. Which skills are worth starting with is shown in our overview in the skills catalog.
One detail that costs time in practice: Cowork sessions and sessions in the cloud, including the scheduled routines, do not read the personal folder ~/.claude/skills/ on your machine. They load the skills enabled for your claude.ai account, plus those in the cloned repository under .claude/skills/. If a scheduled routine calls a purely personal skill, Claude Code simply reports it as not found. So if you want something to run automatically at night, put the skill in the repository or enable it in your account.
One skill, many tools: the format is an open standard
When this article first appeared in July, a SKILL.md was a matter between you and Claude. Since then the format has been published as an open standard, documented on agentskills.io. Anthropic developed it and released it for everyone, and the list of tools that read the same format is long: Cursor, VS Code with GitHub Copilot, Google’s Gemini CLI, OpenAI’s Codex, JetBrains Junie, OpenCode, Goose by Block, Roo Code, Kiro and around three dozen more.
With ChatGPT, however, the common ground ends. OpenAI’s Codex reads the SKILL.md, but in ChatGPT itself the building block is called a Custom GPT and is set up as a configuration in the account, with seven fields in the Configure tab and uploaded knowledge files. For planning, the access question matters most: since 16 August 2026, personal ChatGPT accounts (Free, Go, Plus, Pro) can no longer create new GPTs, nor publish them. Building now only happens in Business, Enterprise or Edu workspaces, and because ChatGPT Business costs 20 US dollars per user on an annual plan and requires at least two seats, the entry point is 40 US dollars a month. How the setup works there and where companies stumble later is covered in Building your own Custom GPT: a guide plus the limits in company use (in German).
That shifts the calculation for companies. The two hours someone puts into good instructions are no longer tied to the tool. If the team switches environments in two years, the folder moves along, because the required fields are the same everywhere. Where else Claude fits into a company is covered in our Claude guide for companies.
The specification knows exactly six fields in the YAML header. name and description are required. Then there is license for the license, compatibility for environment requirements (500 characters at most, for example “Requires git, docker, jq”), metadata as a free collection of your own key-value pairs such as author and version number, and allowed-tools for pre-approved tools, which the specification itself still lists as experimental.
The standard’s reference library checks whether a file is clean:
skills-ref validate ./my-skillStep by step: your first skill
Step 1: Narrow down the use case. The most common mistake is a skill that tries to do too much at once. The best fit is a single, clearly recurring task that can be described in a few sentences, such as the follow-up email from the example above, a particular report format or a fixed checklist before a quote goes out.
Step 2: Create the folder. In Claude Code, a single command in the terminal is enough:
mkdir -p ~/.claude/skills/quote-follow-upThe folder name later becomes the command /quote-follow-up. In claude.ai this step does not apply; there you write a SKILL.md file directly and then upload it as a zip.
Step 3: Write the SKILL.md. The YAML header between the two lines of three hyphens gets at least name and description, followed by the instructions in plain language. You can take the example above directly as a template and adapt it to your own task.
Step 4: Test before you release the skill to others. Make a request that should match the description and watch whether Claude pulls the skill on its own or whether it has to be called directly with /quote-follow-up. Then check how the same request would be answered without the skill, to see the actual difference.
Step 5: Sharpen it based on what you observe. If Claude does not react at all, the description is usually too vague. If Claude reacts to completely different topics, it is too broad. Both can be fixed directly in the text file, with no reinstallation.
The required fields in detail
The YAML header requires two entries, both with fixed rules that Claude checks technically when a skill is created:
name: 64 characters at most, only lowercase letters, digits and hyphens, no XML characters, and the words “anthropic” or “claude” are not allowed as a name.
description: must not be empty, 1,024 characters at most, also without XML characters.
The specification sets three more rules for the name, and an upload fails if one of them is broken: the name must neither start nor end with a hyphen, it must not contain two hyphens in a row (pdf--processing is invalid), and it must match the name of the folder the SKILL.md sits in. So if you rename the folder later, remember the field.
For the naming itself, Anthropic’s best practices guide recommends the gerund form, such as processing-pdfs or analyzing-spreadsheets, because it names the activity directly. Noun forms such as pdf-processing, or names in your own language such as the German angebote-nachfassen, count as equally valid alternatives. What fails in every case are vague names like “helper”, “tools” or “data”: they tell neither you nor Claude what the skill is for, and that backfires as soon as several skills sit side by side.
The description is the real work
Everything else in the SKILL.md is execution, while the description decides whether that execution is ever called at all. Claude uses this one text field alone to choose which of potentially dozens of installed skills fits a request, so this is where most of the care pays off.
Three rules make the difference between a skill that triggers reliably and one that gets ignored:
Always write in the third person. The text ends up unchanged in the system prompt, and a change of perspective confuses the selection. Instead of “I help you with Excel files” or “You can use this for spreadsheets”, write “Analyzes Excel spreadsheets and creates pivot reports”.
Be concrete and name the trigger terms. A description should say both what the skill does and when it should apply. “Helps with documents” is too vague to hold its own against other skills; “Writes follow-up emails for quotes when a quote without a response needs following up” hits the use case exactly.
Better too clear than too reserved. In practice, Claude is more likely to overlook relevant skills than to trigger too many, so the description can be worded a little more forcefully than feels natural at first.
The switches only Claude Code knows
Beyond the six fields of the specification, Claude Code reads its own entries in the YAML header. Four of them are genuinely useful in everyday company work.
disable-model-invocation: true prevents Claude from pulling the skill on its own. It then runs only when someone types /quote-follow-up. For anything that sets something off, such as sending, a deploy or a booking, that is the right setting.
With allowed-tools you approve tools for the duration of the call without a confirmation prompt, and with disallowed-tools you take some off the table, such as questions to the user in a skill that is meant to run unattended. Both approvals last only until the next message.
argument-hint and arguments describe parameters, so that /deploy staging arrives in the skill text as a named placeholder instead of raw appended text.
Finally, context: fork runs the skill in its own sub-context, which pays off for long check runs whose intermediate steps should not clutter the main conversation.
And here lies the trap: the open specification does not know these fields. If you upload the same file to claude.ai or push it through the Skills API, validation answers with a message like this:
Unexpected key(s) in SKILL.md frontmatter: argument-hint.
Allowed properties are: allowed-tools, compatibility, description, license, metadata, nameSo if you want to use the same skill in several places, keep the YAML header to the six standard fields and put the Claude Code switches only into the version that lives in the repository. Claude Code accepts all six spec fields, so in that direction it works without changes.
.claude/commands/deploy.md and a skill .claude/skills/deploy/SKILL.md both create the command /deploy and behave the same way. Existing command files keep working unchanged. New ones still belong in the skill folder, because only a skill brings additional files, the switches above and automatic loading by Claude.When a skill grows: several files instead of one long SKILL.md
For most everyday company cases, a single short SKILL.md is completely sufficient. If a task gets more complex, for example because several variants or an extensive reference are needed, you can extend a skill with further files in the same folder:
quote-follow-up/
├── SKILL.md (short instructions, points to the other files)
├── tone.md (examples of the right tone for each customer)
└── templates/
└── standard.md (ready-made text blocks)Claude opens tone.md or the template only when the task actually requires it, so the files cost nothing as long as they are not needed. Anthropic’s own guideline recommends keeping the SKILL.md itself under 500 lines and setting references only one level deep, so that Claude does not have to jump through several nested files when it looks something up. If you already work with Claude Code and want to know what can be automated beyond individual skills, you will find further examples in our article Claude Code Skills 2026 (in German).
Typical mistakes on the first attempt
Bundling too many tasks into one skill. A skill that is supposed to write quotes, check invoices and summarize reports at the same time rarely has a description that is equally precise for all three cases. Several small skills with clear boundaries almost always beat one big, fuzzy one.
Explaining things Claude already knows. A SKILL.md that first explains what an invoice is before getting to the actual instruction wastes space in the context as soon as the skill is loaded. Only include information that is specific to your own company or task, not general knowledge.
Never testing the skill with real requests. A skill that was only skimmed once while writing often shows its weaknesses only with the second or third real request, for example when the wording differs slightly from what was assumed when the description was written.
Building in time-bound statements. Instructions that say “the old rule applies for now, the new one from next quarter” are bound to go out of date. A clearly named current state is better, plus a separate section for earlier rules if the history stays relevant.
The test routine that shows whether the skill really works
That Claude loads a skill only shows that the description was found, not that the result is better. The reliable test runs in two steps: ask the same realistic request once in a fresh session with the skill active, and once with the same wording without the skill. The difference between the two answers shows without bias whether the skill actually contributes something, or whether Claude would have reached the same result anyway.
A fresh session matters here, because a conversation in which the skill was just written already knows the context from the writing process itself, and that gives a false picture of how well the instructions work on their own.
Anthropic’s best practices guide goes one step further and recommends writing down three such test scenarios before the actual instructions are written. So first let Claude loose on typical tasks without a skill, note where it struggles, and then write the SKILL.md precisely against those gaps. Working the other way round often documents problems that do not exist. Then there is a recommendation that tends to get lost in everyday work: test the skill with every model it will later run on. What is concise enough for Opus can be too little guidance for Haiku.
When you refine a skill in Claude Code, you do not have to restart anything. Claude Code watches the skill directories and picks up text changes to the SKILL.md within the same session. Only when you create a skill directory that did not exist at all when the session started do you need a restart.
Frequently asked questions
Do I need programming skills to create a Claude skill?
No. A SKILL.md is a plain text file with a short YAML header and instructions in plain language, the way you would brief a new colleague. Scripts and code are optional and only needed for advanced cases.
Where do I create my own skill?
In claude.ai under Settings as a zip upload, in Claude Code as a folder with a SKILL.md under ~/.claude/skills/ for all your own projects or under .claude/skills/ for one specific project only, or through the Skills API in your own workspace. The three routes are separate and do not sync automatically.
What is the most important part of the SKILL.md file?
The description field in the YAML header. Claude decides on the basis of this text alone whether a skill fits a request, so it has to be written in the third person and state concretely what the skill does and when it should apply, instead of staying vague.
How do I know whether my skill really works?
Test the same realistic request once with the skill active and once with it switched off, each in a fresh session, and compare the results. Only a before-and-after comparison reliably shows whether the skill triggers and whether it actually delivers better results.
Does a Claude skill also work in other AI tools?
Yes. The SKILL.md format is published as an open standard on agentskills.io and is read by Cursor, VS Code with GitHub Copilot, Google’s Gemini CLI, OpenAI’s Codex, JetBrains Junie and Goose, among others. The condition is that the YAML header sticks to the six fields of the specification: name, description, license, compatibility, metadata and allowed-tools.
Why does claude.ai reject my skill when I upload it?
Usually it contains a frontmatter field that only Claude Code knows, such as argument-hint or disable-model-invocation. Validation in claude.ai and the Skills API accepts only the six fields of the specification and otherwise reports “Unexpected key(s) in SKILL.md frontmatter”. The extra fields belong in the version that lives in the repository.
Sources & references
- Anthropic: official overview of Agent Skills, structure of the SKILL.md, required fields and loading process. platform.claude.com
- Anthropic: best practices guide to writing effective skills, especially on the description and progressive disclosure. platform.claude.com
- Anthropic: documentation on skills in Claude Code, storage locations and test routine. code.claude.com
- Anthropic engineering blog post on the architecture of Agent Skills. anthropic.com
- Agent Skills: full specification of the open format with the six frontmatter fields, the naming rules and the skills-ref validator. agentskills.io
- Agent Skills: overview of the open standard, its origin at Anthropic and the list of tools that read the format. agentskills.io
