How to Learn Claude Skills

Learning Claude Skills means learning a file format, not a new chat habit. Anthropic's Agent Skills overview defines a Skill as a directory of instructions, scripts, and reference files that give Claude a specific way of working. A prompt applies to one conversation. A Skill stays on disk and is loaded only when a request matches it.

You can use Skills Anthropic already ships, or write your own. Both are the same mechanism: once the Skill is available, Claude is supposed to pick it up when the description fits.

What goes in SKILL.md

Every Skill needs a SKILL.md file with YAML frontmatter. Two fields are required.

name is at most 64 characters, lowercase letters, numbers, and hyphens only. It cannot contain the words "anthropic" or "claude", and it cannot contain XML tags. Anthropic's authoring guide suggests a gerund when you can (processing-pdfs, writing-documentation) and says to avoid vague names like helper or utils.

description is required, non-empty, and at most 1,024 characters. It also cannot contain XML tags. It has to say both what the Skill does and when Claude should use it. That sentence is the trigger. At startup Claude loads only the name and description into the system prompt. A vague description means the Skill never runs, or it runs on the wrong request.

The markdown under the frontmatter is the procedure: the steps, the examples, and pointers to other files. The authoring guide says to keep that body under 500 lines. Past that, split the detail into other files and link them from SKILL.md.

A minimal file looks like this:

---name: processing-pdfsdescription: Extract text and tables from PDF files, fill forms, and merge documents. Use when the user mentions PDFs, forms, or document extraction.---
# PDF processing
Use pdfplumber to extract text. For form filling, read FORMS.md.

The overview's own example uses pdf-processing and the same rule: the description names the task and the moment to apply it.

How Claude loads a Skill

Anthropic calls this progressive disclosure. There are three stages, and only the first one is always in context.

1. Metadata. Name and description, loaded at startup. The overview puts this at about 100 tokens per Skill.
2. Instructions. When a request matches, Claude reads SKILL.md from the filesystem with bash. That body is what enters context. The overview caps this stage at under 5,000 tokens.
3. Other files. Extra markdown or examples are read only if the instructions point at them. Scripts run with bash. The script source stays out of context; the output comes back.

Write the body as a table of contents that points at the file the task needs. Assume Claude already knows the general subject. Add the command or the house style it would not know. Do not explain what a PDF is.

A code review can stay as a short list of checks. A migration that must run as one command should say to run that command and not to add flags.

Where a Skill actually runs

The same folder does not follow you automatically. The overview says custom Skills do not sync across surfaces.

• Claude Code. Put the directory in ~/.claude/skills/ for yourself, or .claude/skills/ in a project. Claude Code discovers them from the filesystem. The pre-built PowerPoint, Excel, Word, and PDF Skills are not available in Claude Code.
• claude.ai. Pre-built document Skills are on when you create documents. Custom Skills are zip uploads under Settings > Features, on Pro, Max, Team, and Enterprise, and they require code execution. A custom Skill there belongs to that user. It is not shared across the organization.
• The Claude API. Pass a skill_id in the container parameter together with the code execution tool. Pre-built ids are pptx, xlsx, docx, and pdf. Custom Skills are uploaded through the Skills API and are available to the workspace. In that container there is no network access and no installing packages at runtime.

If you write a Skill in Claude Code and also want it on claude.ai, upload it again. An API upload does not appear in the chat product.

Pre-built Skills cover PowerPoint, Excel, Word, and PDF. Anthropic also publishes an open-source Claude API skill, bundled with Claude Code. The overview points at a skills repository and a cookbook for fuller examples. Use those instead of inventing a second format.

What to practice

Write one Skill for a task you already repeat. Keep the description specific enough that a stranger could predict when it should fire. Put one worked example in the body. If a step is fragile, add a script and tell Claude to run it instead of re-deriving the command.

Then try the same request with the Skill absent and present. If Claude ignores it, the description is the first place to look, not the body. The body is never read until the description matches. Test with each model you expect to use. The authoring guide notes that a Skill written for a stronger model can be too thin for a faster one.

Use Skills you wrote or that came from Anthropic. The overview treats an untrusted Skill like software: it can tell Claude to run tools and code. Read every file in the folder before you enable one you did not write.

A course, not another tab of docs

The format is small. Remembering when to split a file, how the three surfaces differ, and how to test a description is the part people skip. Ailurn turns a prompt, a PDF of the docs, or a repo of example Skills into a course you take, with a lesson order and practice. It does not watch a YouTube tutorial. Start from the AI course builder and ask for a course on writing a SKILL.md file: frontmatter, a description that says when to trigger, a body under 500 lines, and a check that the Skill does not sync between Claude Code, claude.ai, and the API.