SKILL.md Validator

An agent skill is a folder that teaches an AI agent how to do one specific job: process PDFs in a certain way, review pull requests against house rules, write release notes in your team's format. The only file a skill must contain is SKILL.md. Scripts, templates and longer reference documents can sit next to it, but the agent always starts from this one file.

SKILL.md has two parts. At the top is a block of YAML frontmatter, opened by a line of three hyphens and closed by another one. It holds metadata such as name and description. Everything after the closing line is the body: plain Markdown instructions that tell the agent what steps to follow, which files to open and how to handle edge cases.

The split matters because agents load skills in stages. At startup an agent reads only the name and description of every installed skill, which keeps dozens of skills cheap to carry around. When a request matches a description, the agent activates that skill and reads the full body. Supporting files are opened later, only when the body points to them.

This format is described in the open Agent Skills specification, so the same folder can work across Claude Code and other agents that adopted it. That portability is also why small format mistakes hurt. A frontmatter block that does not close, a name with an underscore, or a description that never says when to use the skill can each leave a skill sitting in its folder, never picked up, with no error message anywhere.

The validator above reads a pasted SKILL.md the way an agent would: it splits the frontmatter from the body, parses the YAML, checks every field against the specification and then measures the body against the spec's size guidance. It runs entirely in your browser, is free, and needs no sign up, which matters when a skill describes internal workflows you would rather not paste into a third party server.

The specification defines six frontmatter fields. Two are required, four are optional, and each has its own limits. This table shows them exactly as the validator enforces them.

The name rules are the strictest. Uppercase letters, underscores, spaces and dots are errors, and so are a hyphen at the start or end or two hyphens in a row. So pdf-processing passes while PDF_Processing and pdf-processing- fail. The spec also says the name must match the folder the skill lives in. Since a pasted file has no folder, there is an optional field for the folder name; fill it in and the tool reports an error when the two differ.

metadata is the place for anything the spec does not define, such as an author or a version number. It has to be a mapping, and its values should be strings, so a bare version: 1.0 under metadata produces a warning asking you to quote it.

Before any field is checked, the frontmatter itself must exist and parse. The tool reports an error when the file does not start with the opening hyphen line, when the block never closes, when it is empty, when the YAML is a list instead of key value pairs, or when the YAML parser fails. In that last case the parser's own message is shown, which usually points at the offending line. If you want to see how your frontmatter is being read as data, pasting it into a YAML to JSON converter makes quoting and indentation problems obvious.

Of all the fields, description does the most work. At startup an agent sees only names and descriptions, and it decides whether to activate your skill from that one line. A skill with flawless instructions and a vague description is a skill that never runs. This is the most common silent failure, because nothing errors: the agent simply picks something else or answers without the skill.

A good description answers two questions. What does the skill do, in concrete terms, and when should the agent use it. Compare these:

• Weak: Helps with PDFs.
• Better: Extracts text and tables from PDF files, fills PDF forms and merges multiple PDFs. Use when working with PDF documents or when the user mentions forms or document extraction.

The weak version names a topic but gives the agent nothing to match against. The better one lists the actual operations and the situations that should trigger it, using words a user is likely to type.

The validator nudges you in two ways. A description shorter than 60 characters gets a warning, since it is very hard to cover both the what and the when in fewer characters than that. And if the description contains none of the words "when", "use" or "for", it adds a note suggesting a "Use when" clause. That note is a light heuristic, not a grammar check: a description that contains "for" anywhere will pass it, so read your own description with the agent's eyes as well.

A few habits help in practice. Name the file types, tools or commands the skill handles. Mention the phrases people actually use ("review this PR", "fill out the form"). Avoid internal jargon the user would never say. And keep it under the 1,024 character limit; past that the tool reports an error, and long descriptions also dilute the signal for every other skill the agent is choosing between.

Once a skill activates, its whole body is loaded into the agent's context. Every line you add costs tokens on every activation, so the specification recommends keeping the body under 500 lines and roughly 5,000 tokens, and moving detailed material into separate files in folders like references/.

The validator measures both. Line count is exact. The token figure is an estimate: the trimmed body length in characters divided by 4, rounded up. That ratio is a common rule of thumb for English text, so treat the number as a size signal rather than an exact count. Real tokenizers vary by model and use noticeably more tokens per character for languages such as Chinese, Japanese, Arabic or Hindi. Only the body is counted, not the frontmatter.

Beyond size, the tool checks a handful of structural habits:

• Too short. A body under 20 words triggers a warning; a body with no words at all is an error, because the body is the instruction the agent follows.
• No headings. When a body runs past 15 lines without a single Markdown heading, a note suggests adding sections so the agent can skim.
• Placeholders. Leftover TODO, TBD, FIXME, "lorem ipsum" or "[insert" text is flagged as a warning.
• File references. Markdown links to local files should be relative to the skill root and at most one folder deep, like references/REFERENCE.md. Absolute paths and deeper paths such as references/api/v2/auth.md each get a warning, with up to 3 offending paths listed. Web links and in-page anchors are ignored by this check.

The stats card shows the counts behind these rules: body lines, body words, estimated tokens, headings and file references. If a body is over budget, the usual fix is to keep the steps in SKILL.md and move tables, long examples and API details into a reference file the body links to, so the agent reads them only when a step calls for it.

The Agent Skills specification defines six fields. Claude Code reads those six plus several of its own, which add features like slash command hints or a specific model for the skill. The validator knows these extensions and reports them separately so you can see which parts of your file are portable.

The Claude Code fields it recognizes are argument-hint, disable-model-invocation, user-invocable, model, context, agent, hooks, paths, effort and version. When any of them appear, you get a note, not an error or a warning. They are valid and useful in Claude Code; other agents that follow the spec will simply ignore them. If you only target Claude Code, the note is informational. If you publish a skill for several agents, it tells you which behavior will not carry over.

Any other top level key that is in neither list is reported as a warning with the suggestion to move it under metadata. A custom author: or team: key at the top level is the typical case. The spec reserves the top level for its own fields and gives metadata as the place for everything else, which keeps your file forward compatible when the spec adds new fields. Note that version at the top level is treated as a Claude Code field here; under metadata it is simply custom data.

allowed-tools deserves its own mention. The specification lists it but marks it experimental, and support differs between agents, so the tool always adds a note when the field is present. Its format is also easy to get wrong. The spec expects a single space-separated string such as allowed-tools: Read Grep Bash. Writing it as a YAML list with one tool per line produces a warning, and any other value type, such as a number, is an error.

After you press Validate, the tool shows two cards. The first is the verdict with file statistics. The second is the findings table, sorted so that errors come first, then warnings, then notes.

The three severity levels mean different things:

• Error: the file breaks a rule in the specification. Missing or broken frontmatter, a missing or malformed name, a missing or overlong description, an overlong compatibility and an empty body are all errors.
• Warning: the file is allowed but goes against the spec's guidance, for example a short description, an unknown field, a body over the size budget or a deeply nested file reference.
• Note: information you may want to know, such as Claude Code only fields, the experimental allowed-tools field, or a description without "when to use" wording.

A file is valid when it has zero errors. Warnings and notes do not change that. With no errors the headline reads "Valid SKILL.md"; otherwise it shows the count of errors and warnings. When there are no findings at all, the table says so.

The statistics rows give you the parsed skill name, the number of frontmatter fields, body lines, body words, estimated tokens, headings and file references. The findings table can be downloaded as CSV, which is handy when you are checking several skills and want to keep a record or paste results into an issue. Both cards can also be saved as an image.

It is just as important to know what the tool does not do. It checks one pasted file, so it cannot confirm that the files your body links to actually exist, and it does not run any scripts in the skill folder. It also does not judge whether your instructions are clear, correct or safe; a skill can be perfectly valid and still give the agent poor directions. Everything runs locally in your browser and nothing you paste is uploaded or stored.