A Claude AI skill can look finished and still fail in three quiet ways. It may not load, because a frontmatter field breaks the spec. It may not upload, because claude.ai caps the description at 200 characters while the spec allows 1024. Or it may load and never trigger, because the description is too vague for Claude to pick it. Skill Vision is a Claude Agent Skill validator that finds all three before you ship. It is part of Mr Pirate's tools, and it is listed in the directory as Skill Vision.
What Skill Vision checks
Install it as a skill, then ask Claude in your own words: "validate my skill", "score the quality of my skill and tell me what to fix first", or "is this skill ready to upload to claude.ai?" Claude picks the right inspection and runs it. Under the hood are seven plain Python scripts:
| Check | The question it answers | Script |
|---|---|---|
| Spec conformance | Will this skill load, upload and trigger, by the letter of the Agent Skills spec? | spec_validator.py |
| Token cost | How many tokens does the description cost every session, and the body on trigger? | spec_validator.py |
| Structure and docs | Is the layout sound and the documentation complete? | skill_validator.py |
| Script execution | Do the bundled scripts run, nested packages included? | script_tester.py |
| Quality score | Five dimensions, a grade from A+ to F and an ordered list of fixes | quality_scorer.py |
| Security posture | Credentials, injection and path traversal | security_scorer.py |
| Documentation truth | Do the docs match the code, including "runs offline" claims? | claim_auditor.py |
| Codebase map | What can Claude reach from SKILL.md? Drawn as a Mermaid flowchart | skill_mapper.py |
For the questions no script can settle, such as a stale version number or a citation that does not say what it is cited for, Skill Vision ships a subagent called the hallucination hunter. It runs the scripts first, works from the claims they could not decide, and reports a finding only when it can name the fact that contradicts it.
Why use it instead of reading your skill again
You wrote the skill, so you read it the way you meant it. Skill Vision reads it the way Claude will. Three things make it worth the install:
- The spec wins. Spec conformance and house style are separate verdicts. A short, correct skill is never told to pad itself out to please a style guide.
- It counts context. Every report opens with the skill's cost in tokens. In a 10-skill audit described in the README, context cost varied about 7 times across the corpus, from roughly 0.5k to 4.3k tokens per skill.
- It is tested like a tool you would gate CI on. The validators are covered by 196 adversarial tests, including a parity suite that proves the Mermaid map and the spec verdict cannot drift apart.
The scripts use only the Python standard library, open no network connection and print --json, so a CI pipeline can run the same checks with no model involved. The repository checks itself the same way, and its own report shows its body running over its recommended token budget rather than hiding it.
Install it
git clone https://github.com/AlveeeRahman/skill-vision.git ~/.claude/skills/skill-vision
Use .claude/skills/skill-vision inside a project instead to share it with your team through git. Any Python 3.9 or later works, with no packages and no virtual environment. For claude.ai or Claude Desktop, zip the folder without its .git directory and upload it under Skills.
The rest of the suite
Skill Vision is one of three Claude AI skills I publish together. Research Hound and Agent Oracle cover research and agent design. Agent Oracle's first release was checked with Skill Vision's spec validator before it went out. The documentation site has the full reference.