How to Create Claude Skills: Complete Guide in English (Updated 2026)
I wrote the first version of this guide when Skills were just released. Since then, they've become the standard way to teach Claude a repeatable task: I have one that prepares slides for corporate training courses, with examples taken from the client's industry, and I recently installed a third-party one dedicated to AI SEO, after reading it line by line. This is the updated guide, with what has really changed.
In short. A Skill is a folder with a
SKILL.mdfile: instructions, examples, and optional scripts that Claude loads only when needed. In 2026, Skills exited beta on the API, became an open standard, and in Claude Code absorbed slash commands, with arguments, subagent execution, and tools to measure their effectiveness.
How They Work, in Thirty Seconds
The principle is progressive disclosure, the layered loading I discussed in the article on Claude Code's .md files:
- at startup, Claude sees only the name and description of each Skill;
- when the request matches the description, it reads the body of
SKILL.md; - it opens reference files only if the task requires them, and executes scripts without loading them into context.
This is why you can have dozens of Skills installed without filling the context window: you only pay for the ones you use.
"Skills 2.0": What Really Changed
The name "Skills 2.0" circulates online, but Anthropic hasn't published an official version 2. It's the sum of updates that arrived throughout 2026:
- End of API beta (August 19, 2026): Agent Skills and the Skills API (
/v1/skills) no longer require theskills-2025-10-02header; from late August SDKs, you useclient.skillsinstead ofclient.beta.skills. - Skills from repositories: Claude Managed Agents sessions automatically discover Skills in the
.claude/skillsfolder of a mounted GitHub repository. - Skills and slash commands unified in Claude Code:
.claude/commands/deploy.mdand.claude/skills/deploy/SKILL.mdcreate the same/deploycommand, but the Skill adds support files, invocation control, and automatic loading. - Many new frontmatter fields in Claude Code: arguments, model, effort, subagent execution, paths.
- Hot reload: changes to a Skill take effect immediately, without restarting the session.
- Measurement: evaluations with the
skill-creatorplugin,claude plugin eval, and the/skill-doctorreport on cost and usage of each Skill.
Anatomy of a Skill
article-review/
├── SKILL.md required: frontmatter and instructions
├── checklist.md reference, read only when needed
└── scripts/
└── count.py executed, not loaded into context
The file must start with --- on the first line. The documentation recommends staying under 500 lines and moving details to reference files, citing them from the body:
---
name: article-review
description: Reviews a blog article draft before publication. Use it when the user asks to review, check, or prepare an article for publishing.
when_to_use: Phrases like "review the article", "is it ready to publish?", "check the draft".
allowed-tools: Read Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/count.py *)
---
# Article Review
1. Read the draft indicated by the user.
2. Calculate reading time with `python3 ${CLAUDE_SKILL_DIR}/scripts/count.py <file>`.
3. Check the draft with [checklist.md](checklist.md).
4. Return a list of corrections, from most important.
The Frontmatter: Two Sets of Fields
Here's the most common trap. The open standard Agent Skills provides six fields, the only ones accepted on claude.ai and the API: name, description, license, compatibility, metadata, allowed-tools. An extra field, outside Claude Code, produces a validation error.
Claude Code accepts many others; the most useful:
descriptionandwhen_to_use: these are what Claude reads to decide whether to use the Skill. Together they're truncated at 1,536 characters, so the main use case should be written first.disable-model-invocation: true: only you can start it with/name, and the description doesn't occupy context. Mandatory for anything with side effects, like deploy and commit.user-invocable: false: the opposite, the Skill disappears from the/menu and only Claude uses it.argument-hintandarguments: hints and names for arguments.modelandeffort: model and reasoning level for that turn.context: forkandagent: execution in an isolated subagent.paths: limits automatic loading to files matching a glob.disallowed-tools: tools removed while the Skill is active.
If the Skill must work everywhere, write it with the six standard fields and add Claude Code ones only in the copy you use there.
Arguments, Scripts, and Dynamic Context
A manually invoked Skill receives arguments in $ARGUMENTS, or by position ($0, $1) or by name:
---
name: deploy
description: Publishes the application to production
disable-model-invocation: true
arguments: [environment]
---
Publish to $environment:
1. Run tests
2. Create build
3. Publish and verify the site responds
${CLAUDE_SKILL_DIR} points to the Skill folder and makes script paths portable. The !`command` syntax executes a command before Claude reads the Skill and inserts its output into the text: useful for giving Claude fresh data, like the current diff. If the command fails, the Skill doesn't start; commands respect permission rules, and allowed-tools approves them in advance.
Skills That Work Autonomously: context: fork
With context: fork, the Skill runs in a subagent, without the conversation history, and returns only the result. It should be used for explicit tasks; a Skill made only of guidelines, in a subagent, produces nothing.
---
name: pr-summary
description: Summarizes the changes of a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
## Context
- Diff: !`gh pr diff`
- Modified files: !`gh pr diff --name-only`
## Task
Summarize the changes, risks, and what to test.
By default, the subagent works in the background; with background: false, the response arrives in the same turn.
Where to Put Them
~/.claude/skills/<name>/: personal, valid in all your projects..claude/skills/<name>/in the repository: project-specific, versioned and shared with the whole team.- Inside a plugin: invoked as
/plugin:skilland don't conflict with others. - On claude.ai: Skills enabled on your account are also synced to Claude Code, in
~/.claude/skills/synced/.
To install Skills published by others, across multiple agents, there's the open CLI skills:
npx skills add https://github.com/coreyhaines31/marketingskills --skill ai-seo --agent claude-code --copy
It also creates a skills-lock.json file with the origin and fingerprint of the installed version. The CLI's final message reminds you of the most important rule: Skills run with all the agent's permissions. Before installing one, I download it to a separate folder and read everything: SKILL.md, references, and scripts.
Measuring Whether a Skill Works
A Skill is only valuable if Claude uses it on the right requests and the result improves. The recommended method is baseline comparison:
- choose some realistic requests;
- execute them in new sessions with the Skill active and then disabled (
"skillOverrides": { "name": "off" }); - compare the results. Sessions must be new, because remaining context from creation would hide instruction defects.
The skill-creator plugin automates the cycle: saves test cases in evals/evals.json, launches a subagent for each case, and records tokens and times.
/plugin install skill-creator@claude-plugins-official
For Skills inside a plugin, there's claude plugin eval, which can serve as a CI check. Finally, /skill-doctor shows how much each Skill costs in context and how many times it's used: it's the fastest way to discover unused Skills.
Most Common Mistakes
- Vague description: "helps with documents" never triggers, or always triggers. Write what it does and with which phrases the user requests it.
- Everything in
SKILL.md: beyond 500 lines, move details to references. - Side effects without protection: deploy, commit, and sends require
disable-model-invocation: true. - Claude Code fields uploaded to claude.ai: upload fails, use the six standard fields.
- Third-party Skills installed without reading them: they're instructions you'll execute with your permissions.
Frequently Asked Questions
Skill or slash command?
For new work, Skill: they do everything a command does, plus support files and automatic loading. Existing commands continue to work.
Skill or MCP server?
They complement each other. MCP connects Claude to tools and data; the Skill teaches it how to use them in a precise process.
Do they work on claude.ai and via API?
Yes, with the standard frontmatter. On the API, they've been stable since August 2026.
Summary
Skills are the most economical way to transform a habit into a process: a folder, a Markdown file, and, when needed, a script. In 2026, they became measurable, and that's the important news: a Skill that doesn't improve results in a baseline comparison should be rewritten or removed. If you want to bring this method to your team, let's discuss it in the corporate training courses.

The image in this article was generated using AI.



