👀 Skill Vision

A Claude Agent Skill validator. An Agent Skill for Claude Code that inspects your other skills before they ship — spec conformance, script testing, documentation claims, quality grades, security posture, a Mermaid codebase map, per-skill token cost, and a hallucination-hunting subagent for the claims no script can settle.

GitHub repository Latest release

Install as a Claude Code skill

git clone https://github.com/AlveeeRahman/skill-vision.git ~/.claude/skills/skill-vision

That's the whole install — Python 3.9+, zero dependencies, and no bundled script opens a network connection. Then ask Claude in your own words: "validate my skill", "score the quality of my skill", "is this skill ready to upload to claude.ai?"

What a Claude Agent Skill validator has to check

Tool	Question it answers
`spec_validator.py`	Does the skill load, upload, and trigger per the Agent Skills spec? What does it cost in context tokens?
`skill_validator.py`	Is the structure and documentation sound?
`script_tester.py`	Do the bundled scripts actually run — including nested packages?
`quality_scorer.py`	Five-dimension quality score with an A+ to F grade and an improvement roadmap.
`security_scorer.py`	Security posture — credentials, injection, path traversal — with false-positive-hardened detectors.
`claim_auditor.py`	Does the documentation match the code? Structure and truth fail independently: a skill can conform to the spec and still document a flag its own parser never defines, or claim a script runs offline when it shells out to one that does not.
`skill_mapper.py`	What's actually in the skill, and what can Claude reach from SKILL.md? Draws the skill's files and reference graph as a Mermaid flowchart, off the exact same resolver `spec_validator.py` uses to check links — so the map and the verdict can't disagree.
`agents/hallucination-hunter.md` a subagent, not a script	The judgement half: stale versions, misattributed citations, unsourced numbers, instructions that cannot be followed. Runs the deterministic tools first and works only their `UNVERIFIED` list.

Every tool is a plain stdlib CLI with --json output and CI-friendly exit codes, so pipelines can run the same inspections without Claude in the loop. Where the spec and house opinion disagree, the spec wins — Skill Vision never asks you to pad a concise skill.

Proven in the field

All five validators were run over a private corpus of 10 real, in-use skills. Context cost varied 7× across the corpus, from about 0.5k to 4.3k tokens per skill, which is why every report header states the cost up front. The suite now runs 131 adversarial checks — including a parity suite proving the flowchart and the spec verdict can never drift apart — and the tool reports CONFORMANT (0 errors, 0 warnings) on itself.

Token cost, visible

=== skill-vision  [tool] · ~2.6k tokens (description 115 every session + body 2.5k on trigger) ===

Every report header states what a skill costs in context — description tokens load every session, body tokens on trigger — so heavy skills are visible at a glance.

Where the scripts stop

Every tool above is deterministic: it can prove that a documented flag does not exist, that a script reaches the network, that a count does not match the tree. What it cannot do is tell you a cited paper does not say what it is cited for, that a version number went stale last quarter, or that a benchmark figure has no source. Those need judgement — and judgement is exactly where a model hallucinates.

agents/hallucination-hunter.md is a subagent for that half, built to make guessing expensive. It runs the four tools first and treats claim_auditor.py's UNVERIFIED items as its worklist, rather than reading prose and forming impressions. One rule governs it: every finding names the claim, where it is written, and the specific fact that contradicts it. If it cannot produce that fact, the result is reported as UNVERIFIED rather than as a finding — reporting a suspicion as a defect is itself a hallucination. It reports; it does not fix. And it closes by stating what it did not check, because a report implying coverage it never achieved is the same failure in a different costume.

Copy it into .claude/agents/ to use it.

Project resources

Part of a three-skill suite: Skill Vision (this page) · Agent Oracle · Research Hound