What is a Claude Code skill file?

The short version

A skill is a directory that contains a file named SKILL.md. The file starts with a block of settings between two lines of three dashes, called frontmatter, followed by plain Markdown instructions written for Claude.

Claude Code keeps each skill's name and description in view. When what you ask matches a description, Claude loads the full SKILL.md and follows it. Because the full text loads only when it is needed, a long skill costs very little until it is actually used.

What a SKILL.md looks like

Here is a small example you could adapt. It is our own illustration, not a product file.

---
name: post-outline
description: Drafts a blog post outline from a topic and target reader. Use when the user asks for an outline or a content plan for a post.
---

## Instructions

1. Ask for the topic and the reader if they were not given.
2. Propose a working title and three alternatives.
3. List five to seven section headings with one sentence each.
4. Flag any claim that will need a source before publishing.

According to Anthropic's documentation, no frontmatter field is strictly required, but the description is recommended because Claude uses it to decide when the skill is relevant. If you leave the name out, it defaults to the folder name.

Where skills live

• Personal: ~/.claude/skills/<skill-name>/SKILL.md. Available in all of your projects on that machine.
• Project: .claude/skills/<skill-name>/SKILL.md. Available in sessions in that repository, and you can commit it so teammates get it too.

The documentation lists other locations as well, such as plugin skills and skills synced from a claude.ai account. These options change over time, so check the current documentation for the full list.

Running a skill yourself

You can type a slash followed by the skill name, for example /post-outline, at the start of a message. Per the documentation, a skill runs this way only when its name starts the message. Mentioning the name in the middle of a sentence gives Claude permission to run the skill but does not run it directly.

Adding supporting files

A skill folder can hold more than SKILL.md. Extra files load only when needed, which keeps the main file short.

my-skill/
  SKILL.md        (required: overview and instructions)
  reference.md    (detailed notes, loaded when needed)
  examples.md     (usage examples)
  scripts/
    helper.py     (a script the skill can run)

Mention these files inside SKILL.md so Claude knows when to read them. The documentation recommends keeping SKILL.md itself under 500 lines.

What a skill does not do

A skill is a set of instructions, not a guarantee. Claude can still make mistakes while following it, so review the results before you rely on them or publish them. Only install skills from sources you trust, because a skill can tell Claude to run commands.

Last checked against Anthropic's Claude Code documentation on October 13, 2026. Features change, so confirm details in the current documentation.