SkillsBot.org

SKILL.md Errors and How to Fix Them

The error messages you get when a Claude skill will not upload or load, what each one means, and the fix, checked against Anthropic's documentation.

Most SKILL.md errors come from the first few lines of the file. Paste yours into the SKILL.md validator to find the exact problem, or match the message below.

"SKILL.md must start with YAML frontmatter (---)"

The very first line of the file must be exactly ---. Common causes:

  • Something above the first ---: a blank line, a # Title, or a code fence because the file was copied from a chat window.
  • An invisible character: some editors save a byte-order mark (BOM) at the start of the file. Re-save the file as UTF-8 without BOM.
  • The wrong file in the ZIP: when uploading to the Claude apps, the ZIP should contain the skill folder with SKILL.md inside it, not a folder inside another folder.

A correct start looks like this:

---
name: release-notes
description: Writes release notes from merged pull requests. Use when the user asks for release notes or a changelog entry.
---

In Claude Code a file without this opening line still loads, but Claude Code treats the whole file as instructions and reads no name or description, so the skill rarely triggers on its own.

"SKILL.md must include a skill name and description"

The frontmatter needs both fields. The Agent Skills specification requires name and description, and the Claude apps reject an upload without them.

  • name: up to 64 characters, lowercase letters, numbers and hyphens only.
  • description: not empty, up to 1,024 characters, saying what the skill does and when to use it.

If both are there and you still see this error, the YAML is probably not parsing. The usual cause is a colon followed by a space inside an unquoted value, such as description: Use when: the user asks…. Wrap the value in quotes.

"Description cannot contain XML tags" (or "name cannot contain XML tags")

Anthropic's skill rules forbid XML tags such as <example> in name and description. Move examples into the body of SKILL.md, or describe them in words. In Claude Code, angle brackets in a description are shown escaped as &lt; and &gt;.

"Name cannot contain reserved words"

For skills uploaded to Claude through Anthropic's platform, name cannot contain the words anthropic or claude. Rename the skill, for example pdf-tools instead of claude-pdf.

Skill descriptions are cut short ("skill listing will be truncated")

Claude Code puts every skill's name and description into a listing that has a character budget, about 1% of the model's context window. With many skills installed it drops some descriptions to fit, starting with the skills you use least, and Claude can no longer match those skills to your requests.

Fixes, from Claude Code's documentation:

  • Run /doctor to see the listing's cost, and /skill-doctor to find skills you never use.
  • Turn off skills you do not need, or set low-priority ones to "name-only" in the skillOverrides setting.
  • Put the key use case first in each description: description plus when_to_use is capped at 1,536 characters per skill.
  • Raise the budget with the skillListingBudgetFraction setting (for example 0.02 for 2%).

The skill installs but never triggers

  • The description is too vague. Claude chooses skills by their description. Name the task, the file types and the words a user would type.
  • It is set to manual. disable-model-invocation: true means it only runs when you type /name.
  • It is in the wrong folder. The path must end in <skill-name>/SKILL.md. See how to install Claude skills for every location.
  • It needs another skill. Some skills hand off to others. Matt Pocock's grill-me does nothing useful unless grilling is installed too; we found this in our own test.

SKILL.md errors: FAQ

Why does Claude say SKILL.md must start with YAML frontmatter?

The first line of SKILL.md must be exactly ---. Remove anything above it, such as a blank line, a heading or a byte-order mark, and check that the ZIP contains the skill folder with SKILL.md inside it.

What are the rules for a skill name?

Up to 64 characters, lowercase letters, numbers and hyphens only, with no XML tags. Skills uploaded through Anthropic's platform also cannot use the words anthropic or claude in the name.

Why is my skill description cut short in Claude Code?

The skill listing has a character budget of about 1% of the context window. With many skills, Claude Code drops descriptions of the least used ones. Turn off unused skills, put the key use case first, or raise skillListingBudgetFraction.