How to create a Claude Agent Skill: SKILL.md explained step by step

To create a Claude skill, you make a folder that contains a SKILL.md file: a few lines of YAML frontmatter with a name and a description, followed by Markdown instructions that Claude follows whenever your request matches. You can add reference files and scripts next to it. This guide covers the format rules as Anthropic currently documents them, builds a complete example skill you can copy, and shows how to test it so it triggers when it should and stays quiet when it shouldn't.

What Agent Skills are and when to use one

An Agent Skill is a reusable package of instructions, plus optional files and scripts, that Claude loads on demand. A prompt is something you type for one conversation. A skill sits in the background and loads itself when a request matches its description, so you stop repeating the same guidance in every chat.

Anthropic ships pre-built skills for Word, Excel, PowerPoint and PDF files. Custom skills shine for repeatable work with house rules, and they follow the same prompting principles that work across assistants (see ChatGPT vs Claude vs Gemini prompting):

• Release notes, reports or proposals in a fixed format
• Writing in a brand voice with a terminology list
• Data analysis that follows your team's conventions (which tables, which filters)
• Any workflow with steps people tend to skip

How is this different from a system prompt or custom instructions? Those apply to every message. A skill costs almost nothing until it's needed, so you can install many without crowding the context. If the guidance applies to every conversation, a system prompt is still the right tool. If it applies to a specific kind of task, make it a skill.

Where skills work

According to Anthropic's Agent Skills overview, custom skills work in three places:

• Claude apps (claude.ai). You upload the skill as a zip file and enable it in your skills settings. Code execution must be turned on, and custom skills are individual to each user, so every teammate uploads their own copy. Plan availability has changed over time, so check Anthropic's help center for your plan.
• Claude Code. Skills are plain folders, no upload needed. Put them in ~/.claude/skills/ for personal use across projects, or in .claude/skills/ inside a repository and commit them so your team gets them too. You can also run a skill directly by typing / and its name.
• Claude API. You upload skills through the Skills API, and they run inside the code execution tool's container. Uploaded skills are shared across the workspace. That container has no network access and can't install packages at runtime.

One catch: skills don't sync between these surfaces. A skill uploaded to claude.ai isn't available through the API or in Claude Code, so you add it separately wherever you want it.

How progressive disclosure works

Skills stay cheap because Claude loads them in three stages:

1. Metadata, always loaded. The name and description of every installed skill go into Claude's system prompt at startup. Anthropic estimates this at roughly 100 tokens per skill.
2. Instructions, loaded when triggered. When your request matches a description, Claude reads the body of SKILL.md. Anthropic recommends keeping this body under 500 lines.
3. Resources, loaded as needed. Extra Markdown files are read only when the instructions point to them and the task needs them. Scripts are executed, and only their output enters the context, not their code.

In practice: the description decides whether your skill is used, the body decides how well, and reference files hold what's only sometimes relevant.

The SKILL.md format and its rules

Every skill needs a SKILL.md file shaped like this:

---
name: your-skill-name
description: What the skill does and when Claude should use it.
---

# Skill title

## Instructions

Clear, step-by-step guidance for Claude to follow.

## Examples

Concrete examples of input and expected output.

The rules for the two required fields, per Anthropic's documentation:

• name: maximum 64 characters; lowercase letters, numbers and hyphens only; no XML tags; it can't contain the reserved words "anthropic" or "claude".
• description: must not be empty; maximum 1,024 characters; no XML tags. Anthropic's help center lists a shorter 200-character limit for descriptions in skills uploaded to claude.ai, so stay under 200 if you plan to upload there.

Yes, that means a skill for Claude can't have "claude" in its name. claude-release-notes is invalid; writing-release-notes is fine.

For names, Anthropic suggests the gerund form (verb plus "-ing"), such as processing-pdfs or analyzing-spreadsheets. Noun phrases like pdf-processing are acceptable too. Avoid vague names like helper or utils.

Claude Code is more relaxed: name is optional and defaults to the folder name, and extra fields such as disable-model-invocation: true (manual-only skills) are supported. For a skill that works everywhere, stick to name and description.

Folder layout: SKILL.md, references and scripts

A simple skill is just one file. As it grows, split it:

writing-release-notes/
  SKILL.md
  examples.md
  reference/
    style-guide.md
  scripts/
    collect_changes.sh

Rules that keep it working:

• Link every file directly from SKILL.md. Anthropic advises keeping references one level deep. If SKILL.md points to a file that points to another file, Claude may only partially read the second one.
• Use forward slashes in paths (reference/style-guide.md), even on Windows.
• Name files by content. style-guide.md, not doc2.md.
• Add a short table of contents to any reference file longer than about 100 lines.
• Say whether to run or read a script. "Run scripts/collect_changes.sh" and "see the script for the logic" are different instructions.
• For claude.ai uploads, zip the folder itself, so the skill folder sits at the root of the zip rather than loose files, and make sure the folder name matches the skill's name.

Write a description that triggers correctly

The description is matched against every request, so it does the heavy lifting. Anthropic's guidance: say what the skill does and when to use it, include the words people actually type, and write in the third person, since the description is injected into the system prompt.

Before:

description: I can help you with release notes.

After:

description: Drafts customer-facing release notes from commits, pull request titles or a changelog. Use when the user asks for release notes, a changelog entry, a what's new post or an update announcement.

Why the after works: it names the inputs (commits, PR titles, changelog), the output (customer-facing release notes) and the trigger phrases a real user would say. It's in the third person, and at 192 characters it fits even the stricter claude.ai limit.

Scope cuts both ways: "Helps with writing" fires on unrelated tasks, while "release notes" alone may miss "what shipped this sprint?". List the phrasings you'd naturally use.

A complete worked example: writing-release-notes

Here's a full skill for a fictional invoicing app called Tidepool. Copy the structure and swap in your own rules.

SKILL.md

---
name: writing-release-notes
description: Drafts customer-facing release notes from commits, pull request titles or a changelog. Use when the user asks for release notes, a changelog entry, a what's new post or an update announcement.
---

# Writing release notes

Turn raw engineering changes into release notes a Tidepool customer can read in under a minute.

## Workflow

1. Collect the changes. If the user hasn't provided any and you are in a git repository, run `scripts/collect_changes.sh` and use its output.
2. Drop anything customers can't see: refactors, dependency updates, CI changes, internal tooling.
3. Group what remains under these headings, in this order, skipping empty ones: New, Improved, Fixed.
4. Rewrite each item as one sentence that starts with what the customer can now do. Use the terms in reference/style-guide.md.
5. If a change affects billing, data exports or permissions, add a line starting "Action needed:" that says what the customer must do. If that is unclear, ask the user.
6. Check the draft against the checklist before showing it.

## Output format

Title: "Tidepool [version]: [short theme]"
Then the grouped lists. No intro paragraph and no closing paragraph.

## Checklist

- Every item makes sense without knowing the codebase
- No ticket numbers, branch names or internal codenames
- Under 150 words unless the user asks for more

## Examples

See examples.md for three pairs of raw commits and finished notes.

reference/style-guide.md

# Tidepool release note style guide

- Say "invoice", never "bill" or "statement".
- Say "workspace", not "account" or "org".
- Address the customer as "you". Use the present tense.
- Write dates as "March 4".
- Never promise future features.

examples.md holds input and output pairs, for example:

Input: fix(pdf): correct rounding in multi-currency totals (#482)
Output: Fixed: Invoice totals in mixed currencies now round correctly in exported PDFs.

Three pairs like this teach tone and length better than any adjective; it's the same principle as few-shot prompting.

scripts/collect_changes.sh

#!/usr/bin/env bash
# Prints commit subjects since the latest tag, or the last 50 commits if the repo has no tags.
set -euo pipefail
if last_tag=$(git describe --tags --abbrev=0 2>/dev/null); then
  git log "${last_tag}..HEAD" --pretty=format:"- %s"
else
  git log -n 50 --pretty=format:"- %s"
fi

The script is optional: collecting commits is a deterministic job, and a tested script beats Claude rebuilding the command each time.

Test and iterate

Anthropic's skill authoring best practices recommend building a few evaluation scenarios before writing a lot of instructions. A simple version:

1. Run the task without the skill first. Note exactly where Claude falls short: wrong format, internal jargon, missing "Action needed" lines. Those gaps are what your skill must fix.
2. Write three or more test requests. Some that should trigger it ("write release notes for 2.4", "draft a what's new post from these commits") and a couple that shouldn't ("fix this failing test", "write a blog post about invoicing").
3. Test in a fresh conversation. In Claude Code, check that the skill appears when you type /. In claude.ai, try several prompts and review Claude's reasoning to confirm it loaded the skill.
4. Watch what Claude actually does. Does it skip the checklist? Ignore the style guide? Move critical rules higher, or make them firmer ("MUST").
5. Change one thing at a time, and test with every model you plan to use. A smaller model may need more explicit steps than a larger one.

Common mistakes to avoid

• A vague description like "Helps with documents". Claude can't tell when to use it.
• First- or second-person descriptions ("I can help you...", "You can use this to..."). Use the third person.
• Invalid names: uppercase letters, underscores, spaces, or the words "claude" or "anthropic".
• Explaining what Claude already knows. Every line of SKILL.md competes for context once loaded. Cut the paragraph about what release notes are.
• Nested references that chain from one file to the next. Link everything from SKILL.md.
• A wrong zip structure for claude.ai, with files at the root instead of the skill folder.
• Time-sensitive instructions that go stale silently.
• Installing skills you haven't read. Skills can run code, so Anthropic recommends using only skills from trusted sources and auditing every file, scripts included, before installing anything else.

Skip the blank page

Writing your first SKILL.md is mostly about getting the frontmatter rules and the description right. If you'd rather start from a working draft, the skills generator in Promptay turns a short description of your workflow into a validated SKILL.md package that you can then edit, test and upload. The free plan includes one skill a day. Either way, the testing loop above is what makes it trigger reliably.

Frequently asked questions

Do I need to know how to code to create a Claude skill?

No. The only required file is SKILL.md, which is plain text: two lines of frontmatter and Markdown instructions. Scripts are optional and only worth adding for deterministic steps, such as running a command or validating a file.

Where do I put a SKILL.md file in Claude Code?

Put each skill in its own folder under ~/.claude/skills/ to use it in all your projects, or under .claude/skills/ inside a repository to share it with everyone who works on that project. The SKILL.md file goes directly inside that folder. Claude Code discovers it automatically, and you can also run it by typing / followed by the skill name.

How long can a SKILL.md file be?

The frontmatter has hard limits: 64 characters for the name and 1,024 for the description, with a 200-character description limit listed for claude.ai uploads. For the body, Anthropic recommends staying under 500 lines and moving extra detail into separate reference files that Claude reads only when needed.

Why isn't Claude using my skill?

The most common cause is a description that doesn't match how you phrase requests, so add the words you actually use. Also check that the skill is enabled, that code execution is on in claude.ai, and that you added the skill on the surface you're using, since skills don't sync between claude.ai, Claude Code and the API.