Writing your own Claude skill: structure, SKILL.md, and a description that triggers

A skill is a folder you write to teach Claude a specific way of working, once and for all, instead of retyping the same instructions in every conversation. Unlike a regular message, a skill triggers on its own when it’s relevant, and it can bundle reference files or scripts that Claude only reads if it actually needs them. Here’s how to build one, based strictly on what Anthropic’s official documentation confirms.

The anatomy of a skill folder

A skill is a folder containing, at minimum, a SKILL.md file. In Claude Code, that folder goes in one of two places:

• ~/.claude/skills/<skill-name>/SKILL.md for a personal skill, available across all your projects;
• .claude/skills/<skill-name>/SKILL.md for a project skill, committed to the repository and therefore shared with your team.

A skill can stay a single file, or grow additional files alongside it: a REFERENCE.md for detailed documentation, a FORMS.md for an edge case, a scripts/ folder with executable scripts. None of that is required to start: one SKILL.md file is enough for a first, useful skill.

The frontmatter: the two fields that matter

SKILL.md always starts with a YAML frontmatter, between two --- lines, with two fields:

---
name: your-skill
description: What the skill does, and when to use it.
---

The official documentation is precise about the validation rules for each:

• name: maximum 64 characters, only lowercase letters, numbers, and hyphens, no XML tags, and it cannot contain the reserved words “anthropic” or “claude.”
• description: cannot be empty, maximum 1024 characters, no XML tags, and must describe both what the skill does and when to use it.

On claude.ai, custom skills are installed as a zip archive containing the skill folder at its root (no intermediate subfolder), then enabled from Customize > Skills. The file format and the two frontmatter fields stay the same as locally.

Choosing a good name for the skill

The name deserves more thought than a quick label. The official documentation recommends using a gerund form (verb + “-ing”), such as processing-pdfs, analyzing-spreadsheets, or managing-databases, or failing that, a clear noun phrase like pdf-processing. On the other hand, it explicitly advises against vague or overly generic names like helper, utils, tools, or data: they say nothing about what the skill actually does, either to you once you have ten of them, or to Claude when it has to pick between several available skills. A naming pattern that stays consistent across your skills also makes them easier to maintain, and easier to talk about with Claude.

Writing a description that actually triggers the skill

This is the single most important field in the whole skill: Claude matches your request against the description of every available skill to decide which one to use, possibly among dozens. The official documentation recommends three simple rules. First, always write in the third person: “Processes Excel files and generates reports” rather than “I can help you process Excel files” or “You can use this to process Excel files” — an inconsistent point of view confuses discovery. Second, be specific and include the exact keywords a user would actually use. Anthropic’s own example for a PDF-processing skill:

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.

By contrast, descriptions like “Helps with documents,” “Processes data,” or “Does stuff with files” are explicitly called out as examples to avoid: too vague for Claude to know when to trigger them.

Progressive loading: why a skill costs almost nothing until it’s used

A skill works on three levels, and that’s what lets you install many of them without flooding the conversation’s context. The name and description of every available skill load upfront, at a cost of roughly 100 tokens per skill. The body of SKILL.md is only read once the skill actually triggers, at a recommended cost of under 5,000 tokens (ideally under 500 lines). Additional files and scripts are only loaded or run when SKILL.md’s instructions explicitly point to them — a script runs as a command, and only its output ever enters the context, never its code.

In practice, that means as your skill grows, it’s better to split advanced content into separate files referenced from SKILL.md, rather than keeping everything in one file. The documentation also recommends against stacking references (a file that points to a file that points to another one): keep every reference one level deep from SKILL.md, or Claude risks only reading a partial preview of the deepest files.

Testing your skill

For a Claude Code skill, checking it works is direct:

mkdir -p ~/.claude/skills/my-skill

Write your SKILL.md, then launch Claude Code (claude) from a project and try a request that matches your description, to see whether the skill triggers on its own. You can also force it explicitly with /my-skill. On claude.ai, after enabling it under Customize > Skills, the official documentation recommends trying several prompt phrasings and reviewing Claude’s reasoning to confirm it triggers at the right moment.

Sharing your skill

A project skill, placed under .claude/skills/ and committed to the repository, is automatically shared with anyone who clones the project: no extra step needed. For wider distribution, Anthropic publishes this same format as an open specification (Agent Skills, hosted at agentskills.io), which means a well-written skill stays readable and reusable outside Anthropic’s own products too.

One last word of caution, explicitly repeated in the documentation: a skill can make Claude run commands or scripts, so only install skills you wrote yourself or that come from a source you trust, and read through their content before trusting them, exactly as you would before installing a package or a browser extension.

If you’re planning to use a skill (yours or someone else’s) to help with graded coursework, check your school’s AI usage rules first: that still applies even when the help comes through a skill rather than a regular conversation.

Key takeaways

• A skill is a folder with at least one SKILL.md, placed under ~/.claude/skills/ (personal) or .claude/skills/ (project, shared through the repository).
• Required frontmatter: name (max 64 characters, lowercase/numbers/hyphens, no “anthropic” or “claude”) and description (max 1024 characters, never empty).
• The description must say both what and when, be written in the third person, and avoid vague phrasing.
• Progressive loading: metadata always loads, SKILL.md’s body loads only when triggered, extra files and scripts load only when referenced.
• Test it with a real request matching your description, or force it with /skill-name.
• Only install skills you wrote or whose source you trust, and check your school’s AI rules before using one on graded work.