What is a SKILL.md file?
Agent Skills are an open format for teaching AI agents new capabilities. A skill is a folder that contains a SKILL.md file — YAML frontmatter followed by Markdown instructions — plus optional scripts/, references/, and assets/. The format is defined by the Agent Skills specification at agentskills.io and is read by a growing list of agents, including Claude Code, OpenAI Codex, Cursor, and Gemini CLI.
Two frontmatter fields do the heavy lifting. name is the skill’s identifier, and description is the trigger: agents load the name and description of every installed skill at startup and use the description to decide whether to activate the full skill. A malformed name or an over-long description can make a skill invisible, unreliable, or rejected outright — often silently.
Why validate before you ship?
Discovery breaks quietly. If name doesn’t match the folder name, or description is empty, many agents simply never surface your skill — no error, no warning.
The spec has hard limits. Names are capped at 64 characters with a strict character set; descriptions are capped at 1,024 characters; compatibility at 500. Crossing a limit is exactly the kind of thing a 10-second check catches.
Skills carry real power — and real risk. A SKILL.md can tell an agent to run shell commands. Patterns like curl … | bash, rm -rf, wildcard allowed-tools, or invisible Unicode characters hiding instructions are worth catching in review, whether the risk is accidental or planted by a third-party skill you downloaded.
Metadata isn’t free. Your name + description sit in the agent’s context for every session (the spec budgets roughly 100 tokens for typical metadata). This validator estimates that standing cost so you can keep descriptions tight.
The official rules at a glance
These are the frontmatter fields defined by the official specification (checked 2026-10-23). This validator enforces them as errors; everything else it reports is labelled as a security warning or a best-practice suggestion.
| Field | Required | Official constraints |
|---|---|---|
name | Yes | 1–64 characters; lowercase letters, numbers and hyphens only; must not start or end with a hyphen; no consecutive hyphens; must match the parent directory name. |
description | Yes | 1–1,024 characters, non-empty. Should describe what the skill does and when to use it, with specific keywords. |
license | No | License name or reference to a bundled license file; keep it short. |
compatibility | No | 1–500 characters if provided; environment requirements (intended product, system packages, network access). |
metadata | No | A map from string keys to string values, for additional properties. |
allowed-tools | No | Space-separated string of pre-approved tools. Experimental — support varies by agent. |
Where does each agent look for skills?
The same skill folder works across agents — what differs is where each agent scans for it. Paths below were cross-checked against public documentation and open-source installers on 2026-10-23. Several agents also read the shared ~/.agents/skills/ location, and exact paths can change between versions, so confirm against your agent’s own docs if a skill isn’t discovered.
| Agent | User-wide location | Per-project location |
|---|---|---|
| Claude Code | ~/.claude/skills/ | .claude/skills/ |
| OpenAI Codex | ~/.agents/skills/ | .agents/skills/ |
| Cursor | ~/.cursor/skills/ (also reads ~/.agents/skills/) | .cursor/skills/ (also .agents/skills/) |
| Gemini CLI | ~/.gemini/skills/ (also reads ~/.agents/skills/) | .gemini/skills/ (also .agents/skills/) |
| GitHub Copilot (VS Code) | ~/.copilot/skills/ (also reads ~/.agents/skills/) | .github/skills/ (also .agents/skills/) |
A common setup is to keep one canonical skills folder and symlink it into each agent’s location, so a single SKILL.md serves every tool — which is exactly why validating against the shared base specification, rather than one vendor’s quirks, matters.
FAQ
Is this the official Agent Skills validator?
No. This is an independent, unofficial tool. The specification’s own reference validator is the skills-ref library mentioned on agentskills.io. This page implements the published specification’s frontmatter rules in JavaScript so you can check a file instantly in the browser, and adds clearly-labelled security heuristics and best-practice suggestions on top.
Is my SKILL.md uploaded anywhere?
No. All checking runs in JavaScript on this page, on your device. There is no server, no account, and no analytics on the file contents. You can even save this page and use it offline.
Why does the folder name matter so much?
Because the specification says the name field must match the parent directory name. It is one of the most common reasons a skill silently fails to load: someone renames the folder (or copies the file into a differently-named folder) and the agent can no longer reconcile the two. This validator checks it whenever you provide the folder name.
What does the token estimate mean?
Agents load every installed skill’s name and description at startup, before deciding what to use. The estimate here is deliberately rough — total characters of name + description divided by 4 (a common approximation of ~4 characters per token for English text). Treat it as a budget signal, not an exact tokenizer count: if one skill costs several hundred tokens of standing context, its description is probably doing too much.
Does a clean report mean a skill is safe to install?
No. A clean report means the file follows the specification and none of this tool’s known risky patterns were found. It is a first pass, not a security audit: a skill can be perfectly formatted and still tell an agent to do harmful things in plain language. Always read third-party skills in full before installing them, especially anything that runs shell commands.
Which checks are official rules and which are opinions?
Anything labelled an error comes straight from the official specification (missing or invalid name/description, unclosed frontmatter, folder-name mismatch, the 1,024-character description cap, the 500-character compatibility cap). Warnings are security heuristics (piped remote scripts, destructive commands, wildcard tool approvals, invisible characters). Suggestions are best practice — for example adding a “Use when…” trigger sentence to the description. The full source list is in this project’s README.