SKILL.md validator: check the format and frontmatter
A SKILL.md file is YAML frontmatter between two --- lines followed by Markdown instructions. The name must be lowercase letters, numbers and hyphens, 64 characters at most and equal to the folder name, and the description is required, 1,024 characters at most.
Runs in your browser. The skill you paste stays on this page. By Jake Marsh. Checked against Agent Skills specification (frontmatter fields, name and description limits, directory layout) and Claude Code docs: skills (Claude Code frontmatter fields, 500 line guidance, where skills live) on 2026-11-16.
How to use it
- Paste your SKILL.md, or load the clean or the broken example to see what each check reports.
- Type the folder name the skill lives in. The spec requires it to equal name.
- Optional: paste a file list (one path per line, from find . -type f or git ls-files) to check the layout and every file SKILL.md points to.
- Fix the errors first, then the warnings. Each line names the rule it comes from.
- Copy the report into a pull request or issue if you want a second pair of eyes.
What a valid skill looks like
A skill is a folder with a SKILL.md at its top. Everything else is optional and loaded only when SKILL.md points to it.
release-notes/
├── SKILL.md
├── references/
│ └── style.md
├── scripts/
│ └── format.sh
└── assets/---
name: release-notes
description: Drafts release notes from merged pull requests. Use when the user asks for a changelog.
allowed-tools: Bash(git log:*) Read
---
# Release notes
...The rules this page checks
- name: 1 to 64 characters, lowercase letters, numbers and single hyphens, no leading or trailing hyphen, equal to the folder name. Claude Code reserves anthropic-skills and synced.
- description: required by the spec, 1 to 1,024 characters. Say what the skill does and when to use it. Claude Code cuts description plus when_to_use at 1,536 characters in its skill listing.
- compatibility: 500 characters at most. metadata: a map of string keys to string values.
- Claude Code only fields (context, agent, hooks, paths, effort, model and others) work in Claude Code but make claude.ai uploads and the Skills API reject the file, which accept only name, description, license, compatibility, metadata and allowed-tools.
- Body: under 500 lines and, per the spec, under about 5,000 tokens. Move detail into files one level deep from SKILL.md.
YAML mistakes that break loading
If the frontmatter does not parse, Claude Code loads the skill with no fields at all, so the agent has no description to match and the skill rarely triggers. The usual causes are an unquoted colon inside a description, a tab used for indentation and a missing closing ---. A blank line before the opening --- is worse: Claude Code then reads the whole file, markers included, as instructions.
# breaks: the colon starts a nested key
description: Helps with releases: drafts notes
# works
description: "Helps with releases: drafts notes"Questions
- What is the maximum length of a skill description?
- The Agent Skills spec caps description at 1,024 characters. Claude Code also truncates description plus when_to_use at 1,536 characters in the skill listing it shows the model, so put the trigger words early.
- Does the name have to match the folder?
- Yes. The spec requires name to equal the parent directory name, and it must be lowercase letters, numbers and single hyphens. Claude Code falls back to the folder name when name is missing, but other tools reject the skill.
- Why does my skill never trigger?
- Most often the frontmatter failed to parse, which loads the skill with no fields, or the description says what the skill does without saying when to use it. This checker flags both, along with the YAML mistakes behind most parse failures, such as an unquoted colon in the description.
- Can I use Claude Code fields like context or paths in a skill I upload to claude.ai?
- No. Uploads to claude.ai and the Skills API accept only name, description, license, compatibility, metadata and allowed-tools, and any other field is a hard error. Keep a separate copy for Claude Code if you rely on the extra fields.
- How long can SKILL.md be?
- Keep it under 500 lines. The body is read in full when the skill activates and stays in context, so the spec also recommends under about 5,000 tokens. Put long reference material in separate files and link them from SKILL.md.
Sources
Checked 2026-11-16.
Skills tell the agent how. Taskhold shows what it did.
Once your skills are in place, Taskhold gives Claude Code, Cursor and Codex one task list with steps, progress and questions you answer from your phone.
Or connect your agent first, no sign-up: add https://taskhold.com/api/mcp as an MCP server. The first time it uses Taskhold, it gives you the trial link.
Related tools
- Claude Code slash command generator
Write the prompt once and get the .claude/commands file with the frontmatter, arguments, shell context and allowed tools wired in, plus a preview of what Claude receives.
- Claude Code subagent generator
Fill in a name, a description and a tool list, or start from a code reviewer, debugger or test runner, and get a ready .claude/agents/ file with the frontmatter checked.
- CLAUDE.md and AGENTS.md generator
Answer a few questions about your repo (stack, commands, rules, do-nots) and get a starter CLAUDE.md and AGENTS.md, either as one shared file or as two.