Cx
Log inStart building

Skill Doctor

Your agent ignores the skill, and the field responsible is almost always description.

description is the whole basis on which an agent decides whether to reach for a skill, and the Agent Skills specification asks it to carry both what the skill does and when to use it. Skill Doctor grades exactly that in four checks, then reports every other error, warning and note in the file. No account, nothing to install, no model call on any path.

The analysis runs in this browser tab. The file is not uploaded, not stored, and not sent to a model.

Markdown or plain text, up to 256 KB.

Why another SKILL.md checker

This space is not empty, and Skill Doctor is not trying to have the longest rule list in it. Four things it does differently.

Portability, not just syntax

The specification leaves room and hosts fill it differently, so a finding says which it comes from. allowed-tools is six lines of spec, marked experimental, with no grammar for tool names at all — so an unreadable token is a portability warning here, never a spec violation, and a scope containing a space (Bash(git add *)) is read as the one token it is rather than torn into three. Where a check is the spec's, we cite the spec; where it is our house rule, we say that too.

The spec's rules, and the product's own checks

These are not rules written for a free tool. Skill Doctor calls the same pure, unit-tested validator that runs inside Contexory when someone saves a skill, so a finding here is the finding your team would get there — and the four description checks are the same four the editor scores while a skill is being written. Where the rule is the Agent Skills specification's (the name grammar and its 64-character cap, description from 1 to 1024, compatibility to 500, metadata as a map of strings), the finding cites the spec rather than our preference.

Every finding says which rule, and why

Each error, warning and note links to the reference page that states the rule and the reasoning behind it. You can read it, disagree with it, and ignore it on purpose. A number out of 100 does not let you do that, which is why there isn't one.

Small on purpose

No score, no rule-count race, no paid tier, no account. Errors, warnings and notes grouped by severity, over a file Skill Doctor does not change, keep or publish.

What Skill Doctor does not tell you

Static analysis has a boundary, and a tool that blurs it is worse than one that names it.

  • Whether the skill works. Skill Doctor reads structure and syntax. Whether an agent reaches for the skill at the right moment, and does the right thing once it has, is a question only running it answers.
  • Whether a host obeys allowed-tools. The spec marks the field experimental and says support varies between implementations; in Claude Code it pre-approves tools for a turn rather than restricting anything. Skill Doctor checks that it is well-formed and says nothing about what happens at runtime.
  • Whether name matches its folder. The specification requires a skill's name to equal its parent directory name. Skill Doctor is handed a file, not a folder, so this is the one required rule it cannot check — verify it yourself, or run skills-ref validate ./my-skill against the directory.
  • How your skill compares to anyone else's. Nothing is stored, so there is no history, no score and no leaderboard.

Common questions about validating a SKILL.md

How do I validate a SKILL.md file?
Paste the file into Skill Doctor, or upload it, and it parses the YAML frontmatter and the markdown body and returns every issue it finds, grouped into errors, warnings and notes. Skill Doctor is a free static-analysis tool from Contexory: no account, nothing to install, and no model call on any path. It checks structure and syntax — the name format, whether the description gives an agent something to trigger on, the allowed-tools grammar, body length, and paths that will not resolve on another machine. It cannot tell you whether the skill makes an agent behave correctly, because only running the skill answers that.
Why does a valid allowed-tools value fail validation?
The most common cause is a tool scope that contains a space. Anthropic's documentation for Claude Code gives the example allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *) — three tokens, each with a space inside its parentheses. A checker that splits the field on whitespace turns those three valid tokens into nine fragments and reports an error for every one of them. Of 18 third-party implementations that tokenize this field, 12 split on whitespace. Such a splitter usually passes its own tests, because the Agent Skills specification illustrates the field with Bash(git:*) Bash(jq:*) Read, which has no space inside a scope; the failure only appears against Claude Code's syntax. Skill Doctor instead matches a tool name plus a balanced parenthesised scope, so a scoped command spanning a space is read and validated as one token.
Does allowed-tools stop a skill from using other tools?
No. In Claude Code, allowed-tools pre-approves tools so Claude can use them without prompting you during the turn that invokes the skill, and the grant clears when you send your next message. It does not restrict anything: every other tool stays callable, your permission settings still govern them, and disallowed-tools is the field that removes tools from the pool. This is a frequent bug report — see anthropics/claude-code issues 37683 and 18837, both now closed — but granting rather than restricting is the documented behaviour. One consequence is worth knowing: because the field grants, a token torn apart by a bad split fails closed. The fragment matches no command, the pre-approval simply does not apply, and the agent asks for permission as it would have anyway. Nothing is over-permitted, so a mis-split is a correctness failure rather than a security one. Skill Doctor checks that allowed-tools is well-formed, and makes no claim about what a host does with it at runtime.
Is Skill Doctor free, and is the file I paste stored?
Skill Doctor is free, with no account, no tier and no usage limit. The analysis is entirely static — a parser and a fixed set of rules, with no model call on any path — so a run costs nothing to serve and there is nothing to meter. The file you paste is analysed to produce the report on screen. It is not saved to a Contexory account, not published to the skill gallery, and not used to train anything.
How is Skill Doctor different from other SKILL.md linters?
Of the seven SKILL.md linters we surveyed, six are command-line tools you install and run in CI — the right shape for a repository, the wrong shape for checking one file somebody sent you. Skill Doctor is a page with no account and no install. What it runs is the validator Contexory already uses on skills inside the product — the same pure, unit-tested function, not a separate rule set written for a free tool — so it is deliberately smaller than the linters that advertise rule counts, and it publishes the reasoning behind each rule instead of a score. What it leads with is the field that actually decides whether an agent reaches for your skill: it grades description against the specification's requirement to carry both what the skill does and when to use it. The agentskills.io project also publishes a reference validator, skills-ref validate ./my-skill, if you would rather run conformance checks in your own repository.

Skill Doctor reads one file. Contexory keeps a team's whole library right.

The same checks run in the editor while someone writes a skill, and again before it syncs to Claude Code or OpenClaw. If Skill Doctor found something here, that is where it stops coming back.

See how Contexory worksRead the SKILL.md reference