How to create a SKILL.md file

Before you start

A SKILL.md file defines an Agent Skill, a packaged capability an AI agent loads only when it is relevant. If you are new to the concept, read what is SKILL.md first. The good news: a working skill needs only one file to begin with. You can add scripts and reference files later.

Everything here is plain Markdown with a small block of YAML at the top, so you can write it in any text editor and preview it as you go.

Where skills live

Agent Skills are stored in a `skills` directory, and the location decides their scope:

• Personal skills: `~/.claude/skills/` are available across all your projects.
• Project skills: `.claude/skills/` live in the repo and are shared with your team through Git.

Each skill is its own folder inside `skills/`, and the SKILL.md file sits directly in that folder. The most common mistake is nesting one level too deep. The path must be `skills/your-skill-name/SKILL.md`, not `skills/your-skill-name/another-folder/SKILL.md`.

Step 1: Create and name the skill folder

Make a folder for your skill. The folder name is the skill name, so it has to follow the naming rules:

• Lowercase only, no capitals
• Hyphens between words, no spaces and no underscores
• Up to 64 characters
• Descriptive and specific, for example `pdf-form-filler` or `commit-message-writer`

.claude/
  skills/
    pdf-form-filler/
      SKILL.md

Do not put a README.md inside the skill folder. The SKILL.md is the entry point.

Step 2: Write the YAML frontmatter

Open SKILL.md and start with a YAML block between two `---` lines. Two fields are required:

• name must match the folder name exactly (lowercase, hyphen-case, up to 64 characters).
• description says what the skill does and when to use it. This is the single most important line, because the agent uses it to decide whether to load the skill.

---
name: pdf-form-filler
description: Fill, flatten, and extract fields from PDF forms. Use when the user works with .pdf forms or asks to fill a PDF.
---

Optional fields let you control behavior, such as `allowed-tools` to restrict which tools the skill may use, which acts as a permission boundary.

Step 3: Write the instructions

Below the frontmatter, write the Markdown body. This is what the agent reads once the skill is triggered. Keep it clear and operational: explain the workflow, the steps, and any rules, and include short examples.

# PDF Form Filler

## Instructions
1. Identify the form fields in the PDF.
2. Map the user data to each field.
3. Fill the fields, then flatten the file.

## Examples
- "Fill this PDF with the values in data.json"
- "List the fields in form.pdf"

## Notes
- Never overwrite the original; save a copy.

Keep SKILL.md focused. Aim to stay under about 500 lines and move long reference material into separate files.

Step 4: Add supporting files (optional)

When a skill needs more than instructions, add folders next to SKILL.md and reference them from the body:

• scripts/ for executable code the agent can run for deterministic steps
• references/ for longer documentation, kept under about 200 lines per file
• templates/ for file templates the skill fills in
• assets/ for static files like images or fonts

pdf-form-filler/
  SKILL.md
  scripts/
    fill.py
  references/
    field-types.md
  templates/
    output.json

These files load only when needed, which keeps the skill lightweight at startup.

What a complete SKILL.md looks like

---
name: commit-message-writer
description: Write clear, conventional Git commit messages from a diff. Use when the user asks to write or improve a commit message.
allowed-tools: ["Bash", "Read"]
---

# Commit Message Writer

## Instructions
1. Read the staged diff with `git diff --cached`.
2. Summarize the change in one short subject line.
3. Use the Conventional Commits format: type(scope): subject.
4. Add a body only if the change needs explanation.

## Rules
- Subject under 50 characters, imperative mood.
- Wrap the body at 72 characters.

## Examples
- feat(auth): add password reset flow
- fix(api): handle empty response body

That is a fully working skill: a clear name, a trigger description, optional tool limits, and concise instructions.

How to name a skill well

The name should read like the job it does. Use a verb-plus-object or a clear noun phrase: `pdf-form-filler`, `release-notes-generator`, `sql-query-explainer`. Avoid vague names like `helper` or `utils`, because the agent and your teammates should understand the skill from its name alone. Remember the folder name and the `name` field must match exactly.

Writing a description that triggers reliably

The description is the trigger, so it deserves the most care. State two things: what the skill does, and when to use it. Include the words a user would naturally say. The spec allows a long description (up to 1024 characters), but one or two specific sentences usually work best. Compare a weak and a strong version:

• Weak: "Helps with PDFs."
• Strong: "Fill, flatten, and extract fields from PDF forms. Use when the user works with .pdf forms or asks to fill a PDF."

The strong version names the actions and the triggers, so the agent loads it at the right moment.

Best practices and common mistakes

• One skill, one job. Split broad ideas into focused skills.
• Match the folder name to the `name` field exactly.
• Do not nest SKILL.md an extra level deep inside the skill folder.
• Do not add a README.md inside the skill folder.
• Keep SKILL.md under about 500 lines; push detail into `references/`.
• Commit project skills to Git so the whole team gets them.
• Test the trigger by describing a task in the agent's own words and checking that the skill activates.

Draft and preview your SKILL.md

Because SKILL.md is Markdown with YAML frontmatter, you can write and preview it before you ship it. Use the Markdown Docs online editor to check headings, code blocks, and frontmatter, or download Markdown Docs to edit it on Windows with autosave. For the bigger picture, see AI agent instruction files explained and common .md files for AI projects.

Related references

• Anthropic: skill authoring best practices official authoring guidance.
• Claude Code: extend Claude with skills for creating and using skills.
• How to create custom skills (Claude Help Center) step-by-step setup.