Skip to content
Agents Handbook
PlaybooksJobsAgentsLessonsField logFor agents

SKILL.md validator

Paste a SKILL.md or open a skill folder, and this tool checks it against the Agent Skills specification and Anthropic's skill docs. Each problem comes with its fix and the doc it comes from. It runs in your browser and sends nothing.

The check runs in your browser. Nothing is sent or saved.

Fails the spec

1 error, 3 warnings, 3 hints. 6 checks passed.

Errors (1)

These break the Agent Skills spec. Some clients will not load the skill.

Warnings (3)

The spec allows these, but a client or the reference validator rejects or changes them.

  • Warning

    metadata has values that are not strings

    version (a number). The spec wants string values. Put them in quotes, for example version: "1.0". Unquoted, 1.0 reads as the number 1.

    Source: Agent Skills specification
  • Warning

    1 field only Claude Code reads: argument-hint

    Claude Code accepts these. claude.ai uploads, the Skills API and package_skill.py fail with "Unexpected key(s) in SKILL.md frontmatter". Remove them if you share the skill outside Claude Code.

    Source: Claude Code docs: Skills
  • Warning

    allowed_tools looks like a typo for allowed-tools

    Clients read allowed-tools and ignore allowed_tools, so this setting has no effect. Rename it to allowed-tools.

    Source: Agent Skills specification

Hints (3)

Best practice from the spec and Anthropic's authoring guide.

  • Hint

    description does not say when to use the skill

    The spec says the description should cover what the skill does and when to use it. Add a sentence such as: Use when the user mentions PDFs or forms.

    Source: Agent Skills specification
  • Hint

    description is not in the third person

    Anthropic's guide says to write descriptions in the third person, because they go into the system prompt. Write "Processes Excel files", not "I can help you".

    Source: Claude docs: Skill authoring best practices
  • Hint

    The body uses Windows-style paths

    Found references\forms.md. Anthropic's guide says to use forward slashes, which work on every platform: references/forms.md.

    Source: Claude docs: Skill authoring best practices
Corrected frontmatter
---
name: pdf-tools
description: I can help you with PDFs.
license: Apache-2.0
allowed-tools: Read Bash(python:*)
metadata:
  author: example-org
  version: "1.0"
argument-hint: "[file]"
---
  • name: PDF-Tools becomes pdf-tools.
  • allowed_tools: renamed to allowed-tools.
  • metadata: every value is now a quoted string.

Where to save it

Claude Code, all your projects docs
~/.claude/skills/pdf-tools/SKILL.md
Claude Code, this project docs
.claude/skills/pdf-tools/SKILL.md
Codex, all your projects docs
~/.agents/skills/pdf-tools/SKILL.md
Codex, this repository docs
.agents/skills/pdf-tools/SKILL.md
OpenClaw, this workspace docs
<workspace>/skills/pdf-tools/SKILL.md
6 checks passed

How to use it

  1. 1

    Paste or open your skill

    Paste the SKILL.md text, open the file, or open the whole skill folder. With the folder, the tool also checks that name matches the folder and that every linked file exists.

  2. 2

    Fix errors, then warnings

    Errors break the spec, so some clients will not load the skill. Warnings are rules from one client, such as claude.ai or Claude Code. Hints are best practice. Copy the corrected frontmatter if the tool offers one.

  3. 3

    Install it and test the trigger

    Save the folder at the path shown for your agent. Then ask for the task in plain words and check that the agent loads the skill. If it does not, put the words people use into the description.

Questions

What fields can SKILL.md frontmatter have?

The Agent Skills spec defines six fields: name and description are required, and license, compatibility, metadata and allowed-tools are optional. Claude Code reads more fields, such as when_to_use, disable-model-invocation, model and paths. claude.ai uploads and the Skills API accept only the six spec fields and fail on any other key.

What are the rules for a skill name?

A name is 1 to 64 characters of lowercase letters, numbers and hyphens. It cannot start or end with a hyphen or contain two hyphens in a row, and it must match the skill's folder name. Claude's docs also say it cannot contain the words anthropic or claude.

How long can a skill description be?

The description can be 1 to 1,024 characters. It should say what the skill does and when to use it, in the third person. Claude Code also cuts the description plus when_to_use at 1,536 characters in its skill list, so put the main use case first.

Why is my Claude skill not triggering?

Check two things first: the description must hold the words people use when they ask for the task, and the YAML frontmatter must parse. When the YAML breaks, Claude Code loads the skill with no fields, so Claude cannot match it by its description. A colon and a space inside an unquoted description break the YAML. Paste the file here to find the line.

Where do I put a SKILL.md file?

Put it in a folder named after the skill. For Claude Code, use ~/.claude/skills/name/SKILL.md for all projects or .claude/skills/name/SKILL.md for one project. Codex reads ~/.agents/skills and .agents/skills in the repository. OpenClaw reads the skills folder in its workspace.

Why does claude.ai say Unexpected key(s) in SKILL.md frontmatter?

The frontmatter has a field outside the six in the Agent Skills spec, often a Claude Code field such as argument-hint. claude.ai uploads, the Skills API and package_skill.py reject those keys. Remove them, or keep a separate copy of the skill for Claude Code.

How long should SKILL.md be?

Keep SKILL.md under 500 lines. The agent loads the whole file when the skill starts. Move long reference material into files under references/ and link each one directly from SKILL.md, one level deep.

Sources

Every path, key and command comes from the vendor docs below. We checked them on 2026-10-30.

Related playbooks

Agents
Claude CodeClaudeCodexOpenClawHermes AgentCursorGitHub CopilotGemini CLI
Lessons

More free tools

All free tools