Guide
SKILL.md validator
Paste a SKILL.md or drop a skill folder. You get a 0 to 100 score, every finding with its line, and the tokens the skill costs your agent. It works for Claude Code, Cursor, Codex and Gemini CLI skills.
What it checks
Four checks, 25 points each. Every finding names its rule, so a score is always explainable.
Does the skill follow the Agent Skills format, so every agent can load it?
spec/frontmatterSKILL.md must start with YAML frontmatter, and it must be closed with ---.spec/name-formatname is lowercase letters, numbers and single hyphens, 64 characters at most.spec/description-lengthdescription is 1024 characters at most.spec/non-portable-keysFields claude.ai and the Skills API reject are flagged.spec/broken-refA file the skill points to must exist in the folder.
Is the skill cheap to load and easy to trigger?
eff/description-triggerThe description should say when to use the skill, for example "Use when ...".eff/description-thinA description under 60 characters is too short to trigger reliably.eff/body-tokensThe body is over 5,000 tokens. Split detail into files read on demand.eff/orphan-fileA reference file that SKILL.md never mentions will not be read.
Can an agent follow it the same way twice?
clarity/examplesNo example or code block. One concrete input and output beats extra rules.clarity/outputThe skill never says what the result should look like.clarity/workflowA long body with no numbered steps.clarity/unfinishedA TODO or similar marker left in the text.
Does anything in the folder try to act against the user?
sec/prompt-injectionPhrases that tell the agent to ignore its earlier instructions.sec/remote-execDownloads a script and pipes it into a shell.sec/exfiltrationSends keys, tokens or .env contents over the network.sec/hidden-unicodeInvisible or bidirectional characters that hide text from a reviewer.sec/persistenceWrites to crontab, shell profiles or agent hooks.
Privacy
The validator runs in your browser. Pasted text and dropped files are read on your machine and nothing is uploaded. The only request the page makes is the optional email form, and only if you submit it.
In your terminal and CI
The same scanner ships as a command. Point it at the folders your agents read and set the lowest score you accept.
npx proskills-cli scan .claude/skills .agents/skills --min 80
A skill below 80, or with a critical finding, fails the run before anyone installs it.
Questions
- Is there an official SKILL.md validator?
- The Agent Skills specification at agentskills.io defines the format. This validator checks the same rules (name, description, frontmatter, file references) and adds token, clarity and security checks on top.
- Does my skill get uploaded?
- No. The scanner is plain TypeScript that runs in your browser tab. Your text and files are read and scored there and never sent to a server.
- What score is good enough?
- 80 or more with no critical finding is a sensible bar for a skill you plan to share. Any critical security finding caps the grade at F whatever the rest scores.
- Can I run it in CI?
- Yes. The CLI runs the same scanner. Use --min to set the lowest score you accept and the command exits with an error when a skill falls below it or has a critical finding.
Keep reading
- Skill ScannerScore any skill in your browser. Nothing is uploaded.
- SKILL.md format referenceEvery field, its limit, the folder layout and the errors people hit.
- Skill quality leaderboardScores for every free skill, three synthetic samples, and what 90+ looks like.
- How to write a Claude skillSeven steps, a weak and a strong description, scored side by side.
- All guidesEvery guide, grouped by what you are trying to do.
Paste a SKILL.md or drop a folder. It is scored in your browser and nothing is uploaded.
Want a skill that already passes? Start with a free one.
Grill MeFreeScan 100/100A relentless review of your plan. From the Grill Me collection.