How to create a Claude skill
To create a Claude skill, make a folder with a file named SKILL.md inside, and start that file with a name and a description. The rest of the file is the instructions Claude follows. The steps below follow the Agent Skills spec and Anthropic's best-practice guide, so the same skill also works in other agents.
How do I name the skill folder?
Give the folder the skill's name. Use up to 64 lowercase letters, numbers and hyphens, with no hyphen at the start or end and never two in a row. The folder name and the name field must match. Anthropic also bars the words anthropic and claude in skill names.
~/.claude/skills/processing-pdfs/ SKILL.md
That path is for Claude Code. Other tools use other folders.
What goes at the top of SKILL.md?
SKILL.md opens with YAML between two lines of dashes. Two fields are required.
--- name: processing-pdfs description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. ---
How should I word the description?
This line matters most. The description is how Claude picks a skill, so say what the skill does and name the tasks or words that should trigger it. Write it in the third person, so "Processes Excel files" works and "I can help you process Excel files" does not. You get up to 1,024 characters.
How long can the instructions be?
Below the frontmatter, write the steps in plain Markdown. Keep the body under 500 lines. When it grows past that, move detail into separate files and link to them from SKILL.md. Keep those links one level deep. Claude may only partly read a file that is linked from another reference file, so it can miss what sits deep in a chain.
A skill folder can also hold optional subfolders. Use scripts for code the agent can run, references for docs that it reads only when it needs them, and assets for templates and other files.
How do I test a new skill?
Anthropic suggests that you write a few test tasks first, before you write long instructions for problems the agent may not have. Run the agent on them without the skill, note where it fails, and then write only enough to fix those gaps. To check the frontmatter, run the skills-ref library from the Agent Skills project. In Claude Code, ask a question that should trigger the skill, or call it by name with /processing-pdfs to see whether it loads.
See real skills before you write one
Anthropic's skill-creator skill helps you build new skills. Obra's writing-skills is another example, and you can read both on SkillTrove.
FAQ
Can I make a skill without writing code?
You can. A skill can be nothing but a SKILL.md file of written steps. Code is optional.
How long should SKILL.md be?
Both the spec and Anthropic's guide say to keep it under 500 lines.
Do I need to restart Claude Code after adding a skill?
You don't. Claude Code picks up edits in an existing skills folder during the session. If you created the skills folder itself after the session started, run /reload-skills.