How to Write a Skill for Claude Code So It Actually Works

A skill sits in the folder, runs, and looks like it works. But Claude silently doesn't see part of what's written in it, and doesn't tell you. That's how file loading works: Claude reads SKILL.md only when it has decided the skill fits the task, and the skill's internal files, if there are too many levels of them, it may read only partially.

Anthropic has published a separate guide to writing skills with concrete rules, not general advice. Below is what in it you can really apply to skills you've already installed.

A minimal skill: where to put it and what's inside

A skill is a folder with a SKILL.md file inside. For Claude Code the path is: .claude/skills/<skill-name>/SKILL.md in a project, or ~/.claude/skills/<skill-name>/SKILL.md for personal skills across all projects. A minimal working file looks like this:

---
name: extracting-pdf-text
description: Extracts text and tables from PDF files. Use when working with PDFs, forms, or extracting text from a document.
---

# Extracting text from a PDF

Use pdfplumber:

import pdfplumber

with pdfplumber.open("file.pdf") as pdf:

text = pdf.pages[0].extract_text()

After that you can add separate files (reference.md, examples.md) that SKILL.md links to, but this is enough to start.

The main principle: context is shared, not free

When a session starts, only the name and description of all skills are loaded. SKILL.md itself is read only when the skill becomes relevant to the task. But once it is loaded, every token of it competes for space with the conversation history and the rest of the context.

From this comes the rule: add to a skill only what Claude doesn't know itself. Before each paragraph in SKILL.md it helps to ask yourself whether it justifies its price in tokens, or whether it is an explanation of something the model already understands.

Limits that are easy to break without noticing

The name and description fields in the YAML header of SKILL.md have hard restrictions:

• - name: at most 64 characters, only lowercase Latin letters, digits, and hyphens. Anthropic's guide separately asks not to use the words "anthropic" and "claude" in the name: this is a requirement for skills uploaded through the API or claude.ai. For local skills in Claude Code specifically there is no hard ban, only the folder names synced and anthropic-skills are reserved, but it is worth following the same neutral naming here too, so you don't confuse your skills with system ones.
• - description: at most 1024 characters, and the field cannot be empty.
• - The body of SKILL.md itself is recommended to stay under 500 lines, with the rest moved into separate files.
• - Files that SKILL.md refers to should sit one level of nesting from it. If one file refers to another and that one to a third, Claude may read such a chain partially, with a command like head -100, and miss part of the information.

The description decides whether the skill gets picked at all

Claude may have more than a hundred skills loaded at once, and description is the only thing it uses to pick the right one. It is written in the third person: not "I will help with Excel" and not "You can use this for Excel," but "analyzes Excel spreadsheets, builds pivot tables and charts." Switching between first and third person in a description by itself keeps Claude from choosing the skill correctly.

A good description names both what the skill does and when to use it, with concrete trigger words. "Helps with documents" or "processes data" is not a description, it's a placeholder: Claude doesn't understand at what moment the skill is needed.

Common mistakes found in skills that already work

Too many options in the instruction. A phrase like "you can use library A, or B, or C, or..." makes Claude guess. It is better to name one default tool and separately say when to take the fallback.

Time in the text. Wording like "until August 2025 use the old way, after that the new one" goes stale on its own. The guide recommends keeping outdated options in a separate collapsed "old patterns" block, not in the main flow of the instruction.

Inconsistent terminology. If one place in the skill says "API endpoint" and another says "URL" or "route" about the same thing, Claude spends part of its attention working out that it is the same object.

The degree of freedom doesn't match the task. For operations where any mistake is expensive (a database migration, a final publication), you need an exact command with no right to interpret. For tasks where context determines the best path (code review, analysis), a rigid instruction gets in the way instead.

A checklist before sharing a skill

From the guide you can pull a short list that really takes a few minutes to check:

• - the description names both what the skill does and when to use it;
• - the body of SKILL.md is under 500 lines;
• - no dependence on specific dates;
• - the same terms from start to finish;
• - links to files go directly from SKILL.md, not in a chain;
• - examples are concrete, not abstract descriptions.

I ran this list across my 37 skills in the content factory. Nine of them, all on Three.js, turned out to be beyond the recommended 500 lines, from 520 to 660 lines in the SKILL.md body. The other thirty are fine on length. None of my skills exceeded the 1024-character description limit, but one description took 997 characters, which is already tight, and I put it into a plan to shorten.

If a skill was written long ago and nobody has reviewed it, going through this list once is worth it: some of the problems from this guide are invisible by eye until you read the description specifically against these criteria.

Bottom line

A skill that looks right can silently lose part of its value because of an exceeded description limit, too-deep file nesting, or a first-person description instead of third person. Anthropic's guide gives not general principles but verifiable numbers: 64 characters for the name, 1024 for the description, 500 lines for the body, one level of nesting for links.

I write about working combinations of skills and agents for content and automation in the channel «Растём с ИИ» ("Growing with AI"). A breakdown of a related topic: 5 MCP servers for Claude Code.

If you need to go through your own system of skills and agents in person, you can start with a free consultation.