How to Write a Claude Skill That Loads
How to write a Claude Skill step by step: the SKILL.md syntax, a description that triggers, naming rules, the limits on each surface and a test workflow.

On this page 16 sections
- What is a Claude Skill?
- How do you write a Claude Skill?
- Can you use Claude to write the skill for you?
- Why does the description decide whether a skill loads?
- How long can a skill description be?
- What does the 200-character cap mean for a real skill?
- How do you name a Claude Skill?
- Where do you save, upload and configure a skill?
- How long should a SKILL.md be?
- How do you bundle scripts, permissions and dependencies?
- How do you test a Claude Skill before you trust it?
- Which rules are enforced, and where?
- Do you need to restart Claude Code after editing a skill?
- The Claude Skill checklist
- Where do Claude Skills fit beside MCP?
- Test a product-copy skill against missing facts
Short answer: To write a Claude Skill, create a folder named for the task, add a SKILL.md file with a name and a description that says what the skill does and when to use it, then write step-by-step instructions below. Keep the body under 500 lines, move detail into reference files, and test it on requests that should and should not trigger it.
What is a Claude Skill?
A Claude Skill is a folder containing a SKILL.md file, and nothing else is required. The file opens with YAML frontmatter holding a name and a description, followed by Markdown instructions; optional scripts/, references/ and assets/ folders sit beside it and load only when a task calls for them. Claude uses the description to decide when to apply the skill: the description tells Claude when, and the body tells Claude how.
What Claude Skills are covers the concept, the types and where they run. This tutorial covers the authoring, which has more edges than the concept suggests, and most of them fail silently.
How do you write a Claude Skill?
Writing a Claude Skill takes five steps and one skill file. The format is two required YAML fields and a Markdown body, which is a large part of why dozens of agent products now read it.
- Describe
State when the skill should be used.
- Instruct
Write the task and required steps.
- Test
Try a request that should trigger it.
Writing the file is only part of the job. Test selection as well as execution.
Create the folder
In a terminal or file manager, name it for the job in lowercase with hyphens, for example reviewing-product-copy. Put it in .claude/skills/ for one repository or ~/.claude/skills/ for every project on your machine.
Add SKILL.md
Open the file with a line of three hyphens, a name line matching the folder, a description line, then another line of three hyphens.
Write the description for discovery
Say what the skill does, then when to use it, in the third person. This line decides whether Claude ever opens the rest of the file.
Write the procedure underneath
Brief Claude the way you would brief a careful new colleague who already knows the basics. Include one specific worked example of the input and the output you expect.
Test it in a fresh session
Try a request that should trigger the skill and one that should not, then compare the output with and without the skill.
Here is a complete, minimal SKILL.md, line by line, so the syntax is clear. The description runs to about 145 characters, so it fits every upload path.
Line in SKILL.md | What it does |
|---|---|
| Opens the frontmatter |
| Must match the folder name |
| What the skill does, then when to use it |
| Closes the frontmatter |
| Starts the Markdown body |
| Points to a reference file one level deep |
| The judgement Claude could not guess |
| A fixed output format |
Anthropic's authoring guidance gives one instruction that saves the most rewriting: assume Claude is already very smart. Explaining what a PDF is costs tokens and teaches nothing, so write down only the judgement your team applies that Claude could not work out alone.
Can you use Claude to write the skill for you?
Yes. Ask Claude to generate a skill from a task you just finished and it produces a properly structured SKILL.md with frontmatter, because Claude models handle the format natively. If your team already has process docs, paste one into the chat and ask Claude to turn it into a skill.
Anthropic's best practices describe a two-instance loop. You work a task through with one Claude, ask it to turn what you explained into a skill, then test that skill in a fresh session with a second Claude and bring what went wrong back to the first.
Two shortcuts also exist. Anthropic's skill-creator, in the anthropics/skills repository and also available as a Claude Code plugin, drafts and tests skills, and the help centre describes recording your screen in Cowork on a Mac so Claude can propose a skill from what you did.
Why does the description decide whether a skill loads?
The description is the only part of a skill Claude reads before deciding to use it. At startup an agent loads the name and description of every installed skill, about 100 tokens each according to the Agent Skills specification, and reads the body only once a request matches.
That small token cost is what lets every skill stay listed, and it makes a vague description a silent failure. The skill installs, appears in the listing and never fires, and the symptom looks like Claude ignoring an instruction rather than a metadata problem.
Anthropic's guidance is explicit that the description goes in the third person, because it is injected into the system prompt where a shift in point of view causes discovery problems. A line reading Processes Excel files and generates reports works, and one that opens I can help you does not.
How long can a skill description be?
The description limit depends on where the skill runs, and three different published figures apply. When we checked on 17 September 2026, every authoring guide we read quoted at most one of them.
Where the skill runs | Description limit | Stated by |
|---|---|---|
claude.ai, custom skill uploaded as a zip | 200 characters | |
Agent Skills specification, and the Claude API | 1,024 characters | |
Claude Code | 1,536 characters, counting |
All three were rechecked against their primary sources on 29 October 2026. Only the Claude Code figure is documented as a truncation; the other two are stated as maximums.
So a description that passes the specification at 1,024 characters, and works in Claude Code at 1,536, is still too long for the claude.ai uploader. If you will reuse a skill across multiple surfaces, including the claude.ai uploader, write a short version with the task and its trigger near the start.
What does the 200-character cap mean for a real skill?
The cap means a long description needs rewriting, not trimming. Cutting at 200 characters can remove the trigger clause or split a tool name in half.
As a measured example, take the five skills this site runs internally. Their descriptions were written for Claude Code, where they fit comfortably; measured on 17 September 2026 against the raw frontmatter of each SKILL.md, each would need a shorter version for the claude.ai uploader.
Skill | Description length | Times the 200-character cap |
|---|---|---|
| 904 characters | 4.5x |
| 741 characters | 3.7x |
| 630 characters | 3.2x |
| 367 characters | 1.8x |
| 351 characters | 1.8x |
In the daily-post description, a mechanical cut at 200 characters would split a tool name before the trigger clause. A concise replacement keeps the publishing task and its trigger, then moves tool details into the skill body.
Five skills from one team is an instance, not a study. The part that generalises is the ordering: put the trigger words first, and whatever a short limit removes is the half you can spare.
How do you name a Claude Skill?
A skill name must be 1 to 64 characters of lowercase letters, numbers and hyphens. Under the specification it cannot start or end with a hyphen, cannot contain two hyphens in a row, and must match its parent folder.
Anthropic's naming convention suggests gerund form, so processing-pdfs rather than pdfs, because it names an activity. Noun phrases such as pdf-processing are acceptable too; vague names such as helper, utils and tools tell Claude nothing.
One rule catches many first attempts. Anthropic's platform rejects a name containing the reserved words anthropic or claude, so do not name a skill after the assistant it runs inside.
Where do you save, upload and configure a skill?
Where you save a skill decides who gets it. In Claude Code the name field sets the command you type, and it defaults to the folder name, so a skill at .claude/skills/deploy/SKILL.md runs as /deploy.
Scope | Path or method | Who gets it |
|---|---|---|
Personal skill |
| You, in every project on that machine |
Project skill |
| Everyone working in that repository |
Plugin |
| Anyone who installs the plugin, as |
Enterprise | The managed settings directory | Every user it is deployed to |
claude.ai chat | Zip the folder and upload it under Customize, then Skills | You, on claude.ai and the desktop app |
Claude API | Upload through the Skills API | Everyone in the API workspace |
When two Claude Code skills share a name, enterprise wins, then personal, then project. Personal beats project, so a forgotten copy in ~/.claude/skills/ silently shadows the reviewed one your team committed.
Version-control the project ones. A skill changes how an agent behaves on your codebase, so reviewing it in a pull request is the same argument as reviewing a CI script.
From RankX AIUse a documented procedure with the right tools.Include one unrelated request that should not select the skill and one product with conflicting information that should stop the rewrite.Read the agent-skills referenceHow long should a SKILL.md be?
Keep the SKILL.md body under 500 lines. Both Anthropic's authoring guidance and the Agent Skills specification give that figure, and the specification recommends keeping the instructions under about 5,000 tokens.
Splitting costs nothing because reference files use no context window until Claude reads one. A skill can bundle a complete API reference and still start cheap.
Keep references one level deep from SKILL.md. Anthropic notes that Claude may preview a file reached through another file with a partial read, so give any reference longer than 100 lines a table of contents at the top.
How do you bundle scripts, permissions and dependencies?
A skill can bundle executable code in a scripts/ folder for Claude to run, and Claude can execute that code rather than read it into context, so a long script costs only its output in tokens. Say which you want: Anthropic separates Run analyze_form.py to extract fields from See analyze_form.py for the extraction algorithm.
Declare every dependency, because the runtime differs by surface. On claude.ai a skill can install packages from npm and PyPI; on the Claude API it has no network access and no runtime installs.
The help centre documents an optional dependencies line for uploaded skills, in the shape python>=3.8, pandas>=1.5.0. The specification does not list it, but writing the packages down helps on every surface.
Field | What it does in Claude Code |
|---|---|
| Lets the listed tools run without asking, for the turn that invoked the skill only |
| Removes tools while the skill is active, until your next message |
| Stops Claude from loading the skill on its own; you run it manually with its command |
allowed-tools grants rather than restricts: every other tool stays callable under your normal permission settings. The specification marks the field experimental, so support varies between clients.
How do you test a Claude Skill before you trust it?
Build the evaluations before you write the skill, as the first step of the workflow. Anthropic's guidance is to run Claude on representative tasks with no skill, record where it fails, then write only enough instruction to close those gaps.
- Positive case
The intended request selects the skill.
- Negative case
An unrelated request leaves it alone.
- Execution case
The selected skill completes the permitted task.
A skill that always triggers has not passed a useful selection test.
- Three scenarios, minimum. Each one a real request, with the expected behaviour written down first.
- Test on every model you will use. Instructions enough for Opus can leave Haiku short, and detail that helps Haiku can make Opus over-explain.
- Use a fresh session. Leftover context from writing the skill hides gaps in the instructions, as the Claude Code reference warns.
- Watch how Claude navigates the files. A reference it never opens is either unnecessary or badly signalled from SKILL.md.
- Test the trigger separately. A skill can succeed once invoked and still never invoke itself, which is a description problem, not a procedure problem.
Anthropic's skill-creator automates this loop. In Claude Code it stores test cases in evals/evals.json, runs the cases in separate subagents, one per test case, and grades the output against your expectations.
Its benchmark step runs each case repeatedly and reports the spread with and without the skill, rather than a single pass or fail. That is the honest way to test something probabilistic.
Which rules are enforced, and where?
The Agent Skills specification and Claude Code disagree about what is mandatory, which explains most of the contradictory advice in circulation. The specification requires name and description; Claude Code marks every frontmatter field optional and recommends only description.
Anthropic's own skill-development skill shows the split. Fetched raw on 17 September 2026, its frontmatter read name: Skill Development, with a capital letter and a space, which the specification rejects. It ships in Anthropic's own plugin-dev plugin for Claude Code, and its body ran to 637 lines and 3,196 words, over the 500-line guidance.
The help centre page that documents the 200-character cap uses name: Brand Guidelines as its worked example, capitals and a space again. The validation you get depends on the door you came in through.
Author to the spec anyway, because it is what the other clients read. Its client showcase listed 46 products on 17 September 2026, among them Cursor, GitHub Copilot, VS Code, Gemini CLI, Codex and Goose.
The specification ships a validator for this. Run skills-ref validate ./my-skill before sharing anything: it checks the frontmatter against the naming conventions, which no agent does for you at load time.
Do you need to restart Claude Code after editing a skill?
No. Claude Code watches the skill folders and picks up SKILL.md edits within the current session, so the edit-and-retry loop needs no restart.
Three exceptions remain. A top-level skills folder created after the session started needs /reload-skills, bare mode turns the watching off, and a skill folder that is also a plugin needs /reload-plugins before changes to its hooks, agents or MCP configuration apply.
Guides written earlier in 2026 say to restart after every edit, which was true of an earlier build. Check the date on any skill-authoring guide before you follow it.
The Claude Skill checklist
Run this before sharing a skill with anyone. Each line comes from the specification, Anthropic's authoring guidance or the Claude Code reference, and each fails silently when broken.
nameis lowercase letters, numbers and hyphens, 64 characters or fewer, with no leading, trailing or doubled hyphen, and it matches the folder name.namecontains neitheranthropicnorclaude.descriptionis in the third person and names both what the skill does and when to use it.descriptionfits 200 characters if the skill will ever be uploaded to claude.ai, with the trigger words inside that limit.- The SKILL.md body is under 500 lines, with detail moved into
references/. - Every reference file is one level deep, and anything over 100 lines opens with a table of contents.
- File paths use forward slashes, including on Windows.
- No dates or version cut-offs in the instructions that will quietly become wrong.
- MCP tools are named in full, as
ServerName:tool_name. - Three evaluations exist, run against every model you will use.
skills-ref validate ./my-skillpasses.
Where do Claude Skills fit beside MCP?
A skill teaches procedure and the Model Context Protocol grants access, so a skill that touches a live system needs both. A perfect procedure for a system Claude cannot reach produces a confident description of work that never happened; MCP vs Skills works through the decision.
RankX AI publishes six agent skills for search work, including a visibility audit and a content brief, in the Agent Skills reference, each a single download. They call the RankX AI MCP server, part of the web app for WooCommerce and other websites, so connect the server first and add the skill files second.
Test a product-copy skill against missing facts
Use a small authorised export with a product title, visible specifications and some fields left blank on purpose. Ask the skill for a proposed description and a list of facts it cannot establish.
A useful result keeps unknown materials, certifications, compatibility and delivery promises unknown instead of inventing persuasive details. Include one unrelated request that should not select the skill and one product with conflicting information that should stop the rewrite.
Keep original and proposed fields side by side for review. A skill is a procedure, not permission to edit Shopify or WooCommerce, so require the correct connection and approval for any supported write and start with one reviewed proposal.
Next, understand skills and access or check the connection setup.
Questions about AI Agents and MCP
Can you teach Claude a skill?
Yes, by writing a file rather than by training anything. A skill is a folder with a SKILL.md inside it, holding a name, a description and plain Markdown instructions. Claude reads the description at startup and loads the instructions when a request matches, so no model weights change and no code is required.
Does Claude have a skill creator skill?
Yes. Anthropic publishes a skill-creator skill in the anthropics/skills repository and as an official Claude Code plugin. It drafts the SKILL.md, builds test cases and runs them with and without the skill, so you can see what the skill changed rather than assuming it helped.
What are some examples of Claude Skills?
Anthropic's public repository holds working examples for documents, spreadsheets and slide decks. RankX AI publishes six for search work, including a visibility audit and a content brief. This site also runs five internally, among them a content-review skill and a daily-post skill.
How is a Claude Skill different from a subagent?
A Claude Skill is instructions loaded into the current conversation. A subagent is a separate agent with its own system prompt and its own context window. Skills can hand work to a subagent, and a subagent can preload skills, so the two work together rather than compete.
How is a skill different from pasting a Markdown file into chat?
A pasted file costs its full length in every chat and only works in the chat you paste it into. A skill costs about 100 tokens until a request matches, then loads on its own in any conversation on that surface. It can also bundle scripts that run without entering the context.
How is a skill different from a CLAUDE.md file?
A CLAUDE.md file is loaded into every Claude Code session in that project, so it suits rules that always apply. A skill loads only when a request matches its description, so it suits a procedure you need some of the time.
Sources
- Agent Skills specification, agentskills.io. The frontmatter constraints, the 1,024-character description limit, the name rules and the 500-line guidance. (opens in a new tab) Checked 17 Sep 2026.
- Anthropic, Skill authoring best practices. Third-person descriptions, progressive disclosure patterns, one-level-deep references and evaluation-driven development. (opens in a new tab) Checked 17 Sep 2026.
- Anthropic, Extend Claude with skills (Claude Code reference). Skill paths and precedence, the full frontmatter field list, the 1,536-character truncation and mid-session reloading. (opens in a new tab) Checked 2026-10-21.
- Anthropic help centre, How to create custom skills. The 200-character description maximum for skills uploaded to claude.ai as a zip, the Brand Guidelines name example, and the optional dependencies field. (opens in a new tab) Checked 17 Sep 2026.
- Agent Skills client showcase, agentskills.io. 46 supporting products listed, counted from the page source on 17 September 2026. (opens in a new tab) Checked 17 Sep 2026.
- anthropics/claude-code, plugins/plugin-dev/skills/skill-development/SKILL.md. Fetched raw: 637 lines, 3,196 words, frontmatter name Skill Development. (opens in a new tab) Checked 17 Sep 2026.
- anthropics/skills, the public Agent Skills repository, including the skill-creator skill and its benchmark step, which records runs per configuration and the spread of pass rates with and without the skill loaded. (opens in a new tab) Checked 17 Sep 2026.
- Anthropic engineering, Equipping agents for the real world with Agent Skills. (opens in a new tab) Checked 17 Sep 2026.
CoversThis article covers the AI Agents and MCP topic, the AI Visibility feature and the AI Readiness Score tool.
Terms usedContext Window, Token (LLM) and Knowledge Cutoff.
Read this page asMarkdown: /blog/how-to-write-a-claude-skill.md.
All articlesEverything RankX AI publishes is listed on the blog index.
Ask an assistantAsk ChatGPT (opens in a new tab), Ask Claude (opens in a new tab) or Ask Perplexity (opens in a new tab).
Preferred sourceIf Google is your front door, you can add RankX AI as a preferred source (opens in a new tab), which asks your own results to surface more of what we publish.


