SKILL.md validator

What the validator checks

It runs the same checks Skill Builder runs while you build, against the open Agent Skills specification and common authoring guidance.

Check	Rule
Frontmatter	The file starts with a --- block holding name and description.
Name	1 to 64 lowercase letters, numbers and single hyphens, for example code-review. For a skill it is also the folder name.
Description	Required, up to 1024 characters, and it should say when to use it (“Use when the user asks to…”). Agents read the description to decide when to load a skill.
Compatibility	Optional, up to 500 characters.
Length	Keep SKILL.md under 500 lines, and move long sections (about 60 lines or 700 words) into references/ files.
Files it mentions	A skill that mentions references/api.md or scripts/run.py should ship that file.
Agent model	For agents, model should be a Claude Code alias (haiku, sonnet, opus) or left out to inherit.

Check a whole skill folder

Switch to Files, folder or zip to check a skill with all its files: choose files, choose a folder, drop a folder or drop a .zip. Every skill (a folder with SKILL.md) and agent in it is found, with its references/, scripts/ and assets/, nested folders included, and each gets its own report, file by file. With files, the validator also checks:

• links to files that do not exist, and files nothing mentions;
• paths that moved, and long reference files without a table of contents;
• that the skill’s name matches its folder.

Files that are not text (images, binaries) are listed, not read. Executables and files named like secrets (.env, private keys) block the check.

Syntax checks

Files	What is checked
.json, .toml	Parsed exactly: invalid files are errors, with the line.
.js, .mjs, .cjs, .ts, .py, .yaml, .yml, .xml	Parsed with error-tolerant parsers: likely syntax errors are warnings, with the line.
.html and templates	Inline <script> and onclick=-style handlers are warnings (the builder never renders them, but other tools might).
Shell, PowerShell, Ruby, Perl, CSV, text	Not syntax-checked; the security rules still apply.

Scripts get extra security rules: download-and-run, decoding and running hidden code, reading credentials, dumping the environment, persistence (shell profiles, scheduled jobs) and destructive code block the check; eval, shell commands, network access, package installs, sudo, very long lines and very large scripts are warnings.

Security checks

Skills and agents are instructions an AI follows, and skills can include scripts it runs, so the file is also scanned with the rules Skill Builder applies to every import:

• Secrets: API keys, tokens, passwords and private keys. The value is never shown back.
• Injected instructions: text such as “ignore all previous instructions”, or telling the AI to hide what it did from the user.
• Hidden text: invisible and bidirectional characters, and instructions in HTML comments.
• Dangerous commands: piping a download into a shell, destructive commands, sending local files to the network.

Your file stays on your device

The check runs in your browser. Nothing you paste or choose is uploaded, stored or sent to an AI, and closing the page forgets it. Open in Skill Builder saves it as a project in this browser, only when you click it and only if nothing critical was found.

Common questions

What is a SKILL.md file?

The file that defines an agent skill: YAML frontmatter with a name and a description, followed by markdown instructions. Claude Code, GitHub Copilot and OpenAI Codex read skills from folders in your project. Read how to write a SKILL.md.

Does it check agent files too?

Yes. Switch to Agent to check an agent definition (agents/<name>.md). See skills versus agents for the difference.

My skill passes. Is it safe to install?

Passing means nothing the rules know about was found. It is not a guarantee: read any skill you did not write before you install it, especially its scripts.

How do I fix the problems?

Each finding says what is wrong. To fix them with guidance, open the file in Skill Builder: it shows the same checks next to the text, with one-click fixes for many of them, and exports the skill in the folders Claude Code, Copilot and Codex read.