SKILL.md Validator

What makes a valid SKILL.md

A skill is a Markdown file with a YAML frontmatter block followed by instructions. The frontmatter must include a name and a description, because that description is exactly what an agent reads to decide whether to load the skill for a given task. If the description is vague, the skill either never fires or fires at the wrong time. This validator checks the required structure, then grades the quality signals that determine whether the skill is actually useful and safe to publish.

What the validator checks

• Required frontmatter: a valid --- fenced block with a name and a description.
• Name format: lowercase kebab-case within a sane length.
• Description quality: under about 1024 characters, specific rather than generic, and with clear trigger guidance.
• Body: real instructions below the frontmatter, ideally with a usage or steps section.
• Recommended metadata: version, license, author, and a declared tool scope.

Frequently asked questions

Is my file uploaded when I validate it?

No. The validator runs entirely in your browser. Your SKILL.md never leaves the page, is never logged, and is never stored.

Why does the description matter so much?

The description is the single most important field. Agents use it to route tasks to the right skill, so a specific description that says exactly when to use the skill, such as "Use when the user asks to...", dramatically improves how reliably it triggers. Vague descriptions are the most common reason a good skill sits unused.

Does it fix problems for me?

When trivial fixes apply, it offers a corrected frontmatter block you can copy: it normalizes the name to kebab-case and fills in missing recommended fields with sensible placeholders. Review the placeholders before you ship.

Can I use this before uploading to a marketplace?

Yes. That is a primary use case. Running the validator first catches the conformance and quality issues that get listings rejected or ignored, so your skill is ready before you submit it anywhere.

Where is the official spec?

The spec home is agentskills.io. You can browse real, working examples in our skills library to see the format in practice.