skill-validator CLI
Validates Agent Skills packages: structure, links, token weight and instruction quality, with optional LLM-as-judge scoring
- 265 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- validate links sends HTTP requests to every external link in the skill
- Model scoring passes skill contents to the selected API, local model or your own Claude Code session
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/skill-validatorDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- validate links sends HTTP requests to every external link in the skill
- Model scoring passes skill contents to the selected API, local model or your own Claude Code session
This is third-party code. Review the repository files before installing.
What it does
skill-validator is a Go command-line tool that checks a skill folder before you publish it. The validate structure command compares the directory with the Agent Skills format: SKILL.md frontmatter fields, token limits, code fence integrity, internal links and orphan files nothing points to. The validate links command checks over HTTP and HTTPS that external links still open. The analyze content command computes text metrics: word count, code ratio, imperative sentence ratio, information density and instruction specificity. The analyze contamination command looks for cross-language contamination, where examples in one language can mislead an agent writing in another. The check command runs all four checks without LLM scoring and suits a pre-publish pass. The separate score evaluate command sends the skill to a judge model that rates clarity, actionability and novelty. The score report command merges scores from different models into one report. Output comes as compact text, JSON, Markdown or GitHub Actions annotations. A strict mode lets CI stop on warnings too.
Who it is for. For skill authors and teams that keep skills in a repository and want to catch broken links, bloated files and weak instructions in CI before release.
Good fit when
- You are preparing a skill for release and want to see how many tokens it will take in the agent context
- CI needs a single verdict: check --strict returns exit code 1 on errors and warnings
- Your skill directory needs to be checked before commits through pre-commit
- You want to compare how two models rate the same skill with score report
- The skill has code examples in several languages and you check them with analyze contamination
Not a fit when
- You need a security review of a skill: the tool looks at structure and text quality and does not hunt for malicious commands
- You need a complete offline audit: choose individual structure and text checks, since external link validation makes HTTP requests
- You are checking an MCP server or a plugin: the tool targets folders with SKILL.md
- You want an automatic verdict on whether a skill is useful: the judge score is a hint
Example request
Run skill-validator check --strict on the .claude/skills/ folder and show which skills weigh the most tokens and where links are brokenLimitations
Building from source requires Go 1.25.5 or later. Link checks need network access, including those run by the combined check command. Model scoring can use Anthropic, an OpenAI-compatible endpoint or your own Claude Code CLI session. Cloud calls consume your account limits; local Ollama needs a custom API address and a nonempty key. Claude Code may include project context, making scores less reproducible. The judge library is experimental and its interface may change.
How to disable. Remove the binary with brew uninstall skill-validator or delete the file from go/bin. Drop the pre-commit hook from .pre-commit-config.yaml.
FAQ
How do I check a skill before publishing?
Run `skill-validator check /path/to/skills`, replacing the path with one skill or a parent directory. This checks the package without model scoring. External URLs in the text are still checked over the network.
How do I add skill-validator to pre-commit?
Add the repository to .pre-commit-config.yaml and pick the hook for your agent, for example skill-validator-claude checks .claude/skills/. Hooks exist for Amp, Cline, Codex, Copilot, Cursor, Gemini, Goose, Kiro, Mistral Vibe, Roo Code, Trae and Windsurf. For a custom path use the generic skill-validator hook with args.
Why might a reasoning model return no score?
It can spend the response budget on reasoning. The default budget is 8192 tokens; adjust it with `--max-response-tokens`. A missing score in this case says nothing about the skill’s quality.
What exit codes does skill-validator return?
Code 0 means clean, 1 means errors, 2 means warnings without errors, 3 means bad flags or arguments. With --strict warnings also give code 1, so CI sees only pass or fail.
Can I use skill-validator as a library?
Yes, the orchestrate, judge and evaluate packages can be imported into Go code. For other model providers implement the judge.LLMClient interface with Complete, Provider and ModelName methods.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI to evaluate and evolve agent skills: declarative YAML cases, runs across engines and structured reports
Unit tests for skills: checks that an agent finds and uses your skill. Node 20 and Docker are needed, plus a model key
Caliper runs agent tasks with and without your skill, then shows whether the skill helps and how many tokens it costs
SkillEvaluator
skillevaluator
An NVIDIA framework for evaluating agent skills: quality checks, overlap detection, synthetic checks and live evaluation by an agent. Experimental
Reviews the git diff and the conversation with the agent: catches bugs and gaps between your request and the agent's result. CLI, skill, GitHub Action
A static linter for agent instructions: finds ambiguous tool descriptions and schema gaps before a run, with no model or network
README in short
Go applications can import packages for running checks and model evaluation. A generic pre-commit hook accepts custom skill directories through its arguments.