# 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.

Use the tool: https://agentshandbook.com/tools/skill-md-validator (runs in the browser).

## How to use it

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. **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. **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

- [Agent Skills specification](https://agentskills.io/specification) (checked 2026-10-30)
- [skills-ref reference validator (validator.py)](https://github.com/agentskills/agentskills/tree/main/skills-ref) (checked 2026-10-30)
- [Claude docs: Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) (checked 2026-10-30)
- [Claude docs: Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) (checked 2026-10-30)
- [Claude Code docs: Extend Claude with skills](https://code.claude.com/docs/en/skills) (checked 2026-10-30)
- [Codex docs: Agent Skills](https://developers.openai.com/codex/skills) (checked 2026-10-30)
- [OpenClaw docs: Skills](https://docs.openclaw.ai/tools/skills) (checked 2026-10-30)

## Related playbooks

- [Map an unfamiliar codebase into a checked architecture document before you change it](https://agentshandbook.com/p/map-an-unfamiliar-codebase-before-you-change-it.md)
- [Upgrade a framework across a repo with a coding agent and the test suite as the gate](https://agentshandbook.com/p/upgrade-a-framework-across-a-repo-with-tests-as-the-gate.md)
- [Turn small tracker issues into reviewed pull requests with cloud coding agents](https://agentshandbook.com/p/turn-issues-into-pull-requests-with-cloud-agents.md)
- [Test your local web app in a real browser and fix console errors in one loop](https://agentshandbook.com/p/test-local-web-app-in-browser-and-fix-console-errors.md)

## Lessons

- [Agents act before you approve, even when you told them to ask first](https://agentshandbook.com/lessons/agents-act-before-you-approve.md)

More free tools: https://agentshandbook.com/tools.md