Guide · Agent skill
How to use the Skill Test Validator agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
skill-test is an agent skill that gives Claude Code a checklist for reviewing other skills and agents in a project. A skill is a folder containing a SKILL.md instruction file, and this one checks those files for structure and for whether their behaviour is described correctly. This guide explains what the skill does, how to install it, how to run its four modes and what a pass does and does not prove.
Skill Test ValidatorDonchitos/Claude-Code-Game-Studios · MIT Download the skill Quick start
- 1Download the ZIP. Get the skill-test ZIP from the directory page. It contains SKILL.md.
- 2Unzip into a skills folder. Place the skill folder in ~/.claude/skills/ for all projects, or in .claude/skills/ inside one project.
- 3Confirm the project layout. Make sure your project has studio-tests/, hooks and docs, since the checks assume that structure.
- 4Run a static check. Type /skill-test static with a skill name, or all, to lint its SKILL.md structure.
- 5Run a spec or category check. Use /skill-test spec or /skill-test category on a skill or agent to evaluate its tests or rubric.
- 6Review coverage. Run /skill-test audit to see which skills and agents have specs and when they were last checked.
What the skill-test agent skill does
skill-test validates skill files (.claude/skills/*/SKILL.md) and agent files (.claude/agents/*.md). It has four modes: static runs a structural linter, spec evaluates the assertions in a skill's or agent's test spec, category checks a skill or agent against its category-specific rubric, and audit reports coverage across skills, agent specs and last test dates.
The static linter runs seven checks on each skill: required frontmatter fields, multiple phases, verdict keywords, collaborative protocol language (ask before writing), a next-step handoff, fork context complexity, and argument hint plausibility. Checks can return FAIL or WARN. Agents have no phases to lint, so for an agent static runs only its observations.
Install skill-test in Claude Code or the Claude apps
Download the ZIP from the directory page. It contains SKILL.md. Unzip it so the skill folder sits in ~/.claude/skills/ for all your projects, or in a project's .claude/skills/ folder to use it in that project only.
In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
Check what you need before running it
The skill needs Claude Code or a compatible agent with file read, search and write tools, plus bash, because it calls three helper scripts: yaml-helper.sh, agent-check.sh and compat-inventory.sh. It also expects the surrounding Claude Code Game Studios project files, including the studio-tests/ catalog and rubric, hooks and docs. Those project files are not part of the skill folder, so a copy of the skill alone will not have them.
If you are not working in a project with this studio's layout (studio-tests/, .claude/skills and hooks/yaml-helper.sh), the checks assume a structure that may not match yours.
Run the four modes with the slash command
The skill is user-invocable, and its documented argument syntax is shown below. Pass a skill or agent name, or all where the mode allows it. With no argument, or with audit, it lists coverage.
If the argument is not recognised, the skill prints its usage and stops. If a name has no catalog entry and no matching file in .claude/skills/ or .claude/agents/, it reports that the name was not found and stops.
- static [skill-name | all]: structural linter, about 1k tokens per skill by the skill's own estimate
- spec [skill-or-agent-name]: evaluates test spec assertions, about 5k each
- category [skill-or-agent-name | all]: category rubric, about 2k each
- audit: coverage report, about 3k total
/skill-test static [name|all]
/skill-test spec [name]
/skill-test category [name|all]
/skill-test auditRead the results without overtrusting them
Every mode only reads files. None runs the skill. A static pass means the file has the structure a skill needs, not that it behaves correctly. A spec pass means the instructions cover each case when read closely, not that Claude follows them at run time. A category pass means the skill meets its rubric as written.
To see what a skill actually does, run it on real requests in a throwaway copy of the project, on each model you use, with and without the skill.
Safety notes: scripts, files and network
The skill runs scripts. Its allowed tools include bash calls limited to the three helper scripts named above, plus Read, Glob, Grep and Write. It also runs a config lookup when it loads. It has no network access.
Writes follow the automation mode in your project settings. In collaborative mode the skill asks before every file write. In guided mode it asks only for major changes. In autonomous mode it logs its actions and proceeds, except for categories set to always prompt.
- Reads and writes are limited to the project files it is given access to
- Network use: none
- Automation mode is set in project.local.yaml or project.yaml, defaulting to collaborative
What people use it for
- Lint every SKILL.md in a skill library for consistent frontmatter and phase structure with static all.
- Check a new skill for ask-before-write language and a next-step handoff before sharing it.
- List which skills and agents have test specs and when each was last checked with audit.
- Run a category rubric on one agent to see whether it meets its category's metrics.
Frequently asked questions
Is the skill-test agent skill free?
The skill is listed under the MIT licence. The source does not state any price, so check the licence terms on the directory page for details.
How do I install skill-test in Claude Code?
Download the ZIP and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, upload it under Settings → Capabilities → Skills.
What do I need to run skill-test?
You need Claude Code or a compatible agent with file read, search and write tools, and bash for its three helper scripts. You also need the studio project files, such as studio-tests/, hooks and docs, which are not in the skill folder.
Does skill-test need internet access?
No. The skill is listed as not using the network, but it does run scripts through bash.
Why does skill-test say the CCGS Skill Testing Framework folder was renamed?
Older projects used a folder called CCGS Skill Testing Framework/. The skill now reads only studio-tests/, so you need to move any specs you wrote there. The source points to UPGRADING.md for how to do this.
Does a passing skill-test result mean my skill works?
No. A pass means the file is well-formed or its instructions cover each case when read. To judge real behaviour, run the skill on real requests and compare results with and without it.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
skill-test suits maintainers of a Claude Code skill library and developers who want a quick structural check before sharing a SKILL.md. It is a poor fit if you want to know whether a skill works for end users, or if your project does not follow the studio's folder layout. For behaviour, run the skill on real requests instead.
Download the skill