CLI Coming Soon
    Back to catalog

    SKILL.md validator: check a Claude skill against the Agent Skills spec

    Published · Last updated · Spec checked 2026-11-11

    Paste a SKILL.md or drop a skill folder. The validator checks it against the Agent Skills specification: frontmatter, the required name and description, their limits, optional fields and folder layout. Each result links to its spec section. Nothing leaves your browser.

    Check your SKILL.md

    Runs in your browser. Nothing you paste or drop is uploaded or stored.

    Results show here as soon as there is something to check.

    A valid SKILL.md

    This passes every check when it sits in a folder named pdf-processing/. The name and description come from the spec's own examples.

    ---
name: pdf-processing
description: 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 PDFs, forms, or document extraction.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

# PDF processing

## Steps

1. Read the PDF with scripts/extract.py.
2. For forms, follow [the forms guide](references/FORMS.md).
3. Return the extracted text and tables as Markdown.

## Edge cases

- Scanned PDFs have no text layer. Say so and stop.

    The folder around it, as the spec lays it out:

    pdf-processing/
├── SKILL.md          # required
├── scripts/          # optional: code the agent can run
├── references/       # optional: docs loaded on demand
└── assets/           # optional: templates, images, data

    Rules this validator checks

    A "must" rule fails the file. A "should" rule is a recommendation from the spec and shows as a warning.

    RuleWhat the spec saysLevel
    SKILL.md at the skill root"A skill is a directory containing, at minimum, a SKILL.md file." Directory structuremust
    Starts with YAML frontmatter"The SKILL.md file must contain YAML frontmatter followed by Markdown content." SKILL.md formatmust
    Frontmatter is valid YAML key-value pairs"The frontmatter is YAML with the fields from the spec's frontmatter table." Frontmattermust
    name is present"name: Required." Frontmattermust
    name is 1 to 64 characters"Must be 1-64 characters." name fieldmust
    name uses lowercase letters, numbers and hyphens"May only contain unicode lowercase alphanumeric characters (a-z, 0-9) and hyphens (-)." name fieldmust
    name does not start or end with a hyphen"Must not start or end with a hyphen (-)." name fieldmust
    name has no consecutive hyphens"Must not contain consecutive hyphens (--)." name fieldmust
    name matches the folder name"Must match the parent directory name." name fieldmust
    description is present and not empty"description: Required. Non-empty." description fieldmust
    description is at most 1024 characters"Must be 1-1024 characters." description fieldmust
    license is a short string"Optional. License name or reference to a bundled license file." license fieldmust
    compatibility is 1 to 500 characters"Optional. Must be 1-500 characters if provided." compatibility fieldmust
    metadata maps string keys to string values"Optional. A map from string keys to string values." metadata fieldmust
    allowed-tools is a space-separated string"Optional, experimental. A space-separated string of tools that are pre-approved to run." allowed-tools fieldmust
    Only fields the spec defines"The frontmatter table lists name, description, license, compatibility, metadata and allowed-tools. metadata holds additional properties not defined by the spec." Frontmattershould
    Markdown instructions after the frontmatter"The Markdown body after the frontmatter contains the skill instructions." Body contentshould
    SKILL.md under 500 lines"Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files." Progressive disclosureshould
    Instructions under about 5,000 tokens"Instructions (< 5000 tokens recommended): the full SKILL.md body is loaded when the skill is activated." Progressive disclosureshould
    File references are relative to the skill root"When referencing other files in your skill, use relative paths from the skill root." File referencesshould

    How it works

    1. It looks for a line with only --- on line 1 and a second --- line that closes the frontmatter. Everything after that is the Markdown body.
    2. It parses the frontmatter with the yaml library (version 2.6.0, pinned) using the YAML 1.2 core schema. A parse error fails the file and shows the line.
    3. It runs the rules in the table above. Character counts use code points, the same way the spec's reference library counts them. The name is normalized (Unicode NFKC) before it is compared with the folder name.
    4. The token count is a rough estimate: body characters divided by 4. It is not a real tokenizer, so treat the 5,000-token line as a guide.
    5. When you drop a folder, it also checks that SKILL.md sits at the folder root and that local links in the body point to files that exist in the folder.

    The rules come from the spec page at https://agentskills.io/specification, read on 2026-11-11. Its source file last changed in commit 217be54 on 2026-08-04.

    What it does not check

    • Whether the description is good. The spec says it should say what the skill does and when to use it, which is a judgment call. Compare yours with the spec's good and poor examples.
    • Reference chains. The spec asks you to keep file references one level deep from SKILL.md. The validator does not open the referenced files.
    • Whether scripts run, or what any agent product does beyond the spec.

    For a command-line check, the spec points to skills-ref: skills-ref validate ./my-skill.

    FAQ

    What is a SKILL.md validator?

    A tool that reads a skill's SKILL.md and tells you whether it follows the Agent Skills specification: the frontmatter block, the required name and description fields, their length and character limits, and the folder layout. This one runs in your browser and links every failed check to the spec section it comes from.

    What is the SKILL.md format?

    A Markdown file with YAML frontmatter at the top. The spec says the file "must contain YAML frontmatter followed by Markdown content" (SKILL.md format). The frontmatter needs name and description. license, compatibility, metadata and allowed-tools are optional. The Markdown body holds the instructions the agent follows.

    Which fields are required in SKILL.md?

    Two: name and description (Frontmatter). name is 1 to 64 lowercase letters, numbers and hyphens, with no hyphen at either end and no "--". description is 1 to 1024 characters.

    Does the name have to match the folder name?

    Yes. The spec says name "must match the parent directory name" (name field). A skill in a folder called pdf-processing/ needs name: pdf-processing. Drop the folder, or type its name in the box above, to check this.

    How long can a skill description be?

    1024 characters at most, and it cannot be empty (description field). The spec also says it should cover what the skill does and when to use it, with keywords that help an agent match it to a task.

    Is this the same as skills-ref validate?

    It checks the same frontmatter rules as skills-ref, the reference library the spec points to, and adds the spec's size and file-reference recommendations as warnings. Two differences: skills-ref treats unknown frontmatter fields as errors, this tool warns. And skills-ref reads every YAML value as text, so it does not flag an unquoted version: 1.0 in metadata; this tool warns, because most YAML parsers read it as a number.

    Is my SKILL.md uploaded anywhere?

    No. The checks run in JavaScript in your browser. There is no backend and no API key. Files you drop are read locally with the browser's File API.

    Do Claude skills use this format?

    Yes. Claude skills are SKILL.md folders in the Agent Skills format, which Anthropic donated to the Agentic AI Foundation on October 22, 2026. Our guide covers what changed for skill authors.

    Skills in the catalog to compare with

    Related

    Sources

    All checked 2026-11-11.