FREE TOOL · RUNS OFFLINE

SKILL.md validator

Paste an agent skill's SKILL.md. See whether it passes the Agent Skills spec, a claude.ai upload (the Skills API has the same rules) and Claude Code, with the fix for each problem. It also looks for API keys. Nothing leaves your browser.

Result

Paste a SKILL.md and press “Check the skill”.

    What it checks, and who refuses what

    Three readers, three sets of rules. The Agent Skills specification is what Codex, Copilot, Cursor, Gemini CLI and the other agents read. A claude.ai upload, the Skills API andpackage_skill.py accept only the spec's six fields. Claude Code accepts more. Checked against the three sources on 18 November 2026.

    SKILL.md rules by target
    RuleSpecclaude.ai uploadClaude Code
    Frontmatter opens on the first line with ---requiredrequiredelse the whole file is the instructions
    name: 1-64 characters, a-z, 0-9 and hyphens, no hyphen at the start or end, no --requiredrequiredoptional, defaults to the folder
    name equals the folder namerequirednono
    No "anthropic" or "claude" in the name, no XML tagsnorequiredno
    description: 1 to 1,024 characters, what it does and when to use itrequiredrequiredrecommended; else the first line of text
    Only name, description, license, compatibility, metadata, allowed-toolsother fields ignoredrequiredaccepts its own 14 more
    compatibility up to 500 characters, metadata a map of textrequiredrequiredmetadata ignored
    Under 500 lines and about 5,000 tokens; references one level deeprecommendedrecommendedrecommended

    A worked example. A deploy skill with argument-hint: [environment] anddisable-model-invocation: true works in Claude Code. Uploaded to claude.ai it stops withUnexpected key(s) in SKILL.md frontmatter: disable-model-invocation, argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name, the error Anthropic's docs quote. Other agents read the skill and ignore both fields. The validator says all three at once.

    The wording checks are ours, from Anthropic's authoring guide: a description should say when to use the skill, in the third person ("Formats SQL ..."), and be long enough to tell it apart from others. They are warnings, not failures. A key from a known vendor (GitHub, AWS, Stripe and about 120 more, by keysnitch) fails every target: a skill is shared and sent to the model.

    What 1,792 public skills got wrong

    On 18 November 2026 we ran this validator on 1,792 different SKILL.md files from 1,553 GitHub repositories (code search, 200 files in each of ten size bands, copies removed). Of the 1,601 with frontmatter:

    • 38.2% would be refused by a claude.ai upload, mostly for extra fields such as version and author;
    • 18.3% break the Agent Skills spec: a missing name, a name that is not the folder's, or nested metadata;
    • 36.6% describe what the skill does but never say when to use it;
    • 191 more files called SKILL.md had no frontmatter at all.

    The full study, with the fixes and the format explained: SKILL.md format: rules, examples and 1,792 public skills checked. How Claude Code chooses a skill, tested on 72 runs: Claude Code skills.

    Give every agent your team's skills

    Agent Ready keeps your company's and each Jira project's skills in one library. Import a SKILL.md, a .zip or an npm package; the skills for a work item's roles go to the agent with the work item, in the brief or through MCP. A skill with a key in it is not saved.

    Frequently asked questions

    Why does Claude Code load my skill when claude.ai refuses it?

    Claude Code accepts its own frontmatter fields, such as argument-hint, disable-model-invocation and model. A claude.ai upload, the Skills API and package_skill.py accept only the six fields of the Agent Skills spec and stop with "Unexpected key(s) in SKILL.md frontmatter". Keep a shared skill to name, description, license, compatibility, metadata and allowed-tools.

    Is the skill I paste sent anywhere?

    No. The check runs in your browser. The page has no analytics, and its Content-Security-Policy (connect-src none, form-action none) forbids it from sending any request, so it also works offline.

    Does a pass mean the agent will use my skill?

    No. A pass means the file is well formed. Whether an agent picks it depends on the description: in our test in Claude Code, a description that said when to use the skill was picked on 15 of 15 runs that needed it, the same skill without the "when" on 9 of 15.

    Where should a SKILL.md live?

    In a folder named like the skill: .claude/skills/<name>/SKILL.md for Claude Code, .agents/skills/<name>/SKILL.md for Codex and several other agents, .github/skills/<name>/SKILL.md for GitHub Copilot. The name field must match the folder name.