/skill-test

name: skill-test
description: "Validate skill files for structural compliance and behavioral correctness. Four modes: static linter, spec, category rubric, audit."
argument-hint: "static [skill-name | all] | spec [skill-or-agent-name] | category [skill-or-agent-name | all] | audit"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash(bash "*/.claude/skills/skill-test/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/agent-check.sh*), Bash(bash .claude/scripts/compat-inventory.sh*)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation`

**Automation mode**: Resolve `modes.automation` (`project.local.yaml` → `project.yaml` → default `collaborative`). Every `AskUserQuestion` call and every file write follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt).

Skill Test

Validates skills (`.claude/skills/*/SKILL.md`) and agents (`.claude/agents/*.md`) for structural compliance and behavioral correctness. No external dependencies — runs entirely within the existing skill/hook/template architecture.

**Four modes:**

| Mode | Command | Purpose | Token Cost | |------|---------|---------|------------| | `static` | `/skill-test static [name\|all]` | Structural linter — 7 compliance checks per skill, plus agent, delegation and compatibility observations | Low (~1k/skill) | | `spec` | `/skill-test spec [name]` | Behavioral verifier — evaluates assertions in a skill's or agent's test spec | Medium (~5k each) | | `category` | `/skill-test category [name\|all]` | Category rubric — checks a skill or agent against its category-specific metrics | Low (~2k each) | | `audit` | `/skill-test audit` | Coverage report — skills, agent specs, last test dates | Low (~3k total) |

**What a pass proves.** Every mode reads files; none runs the skill. `static`: the file has the structure a skill needs, not that it behaves. `spec`: read closely, the instructions cover each case, not that Claude follows them when it runs. `category`: the skill meets its category's rubric as written. `audit`: which skills and agents have specs, and when each was last checked. What a skill does shows only when it runs: a real request in a throwaway copy of the project, on each model you use, with and without the skill (Anthropic's Agent Skills best practices, "Build evaluations first").

---

Phase 1: Parse Arguments

Determine mode from the first argument:

• `static [name]` → run 7 structural checks on one skill, or the agent observations on one agent
• `static all` → run 7 structural checks on all skills (Glob `.claude/skills/*/SKILL.md`), plus the observations for every agent
• `spec [name]` → read the skill or agent + its test spec, evaluate assertions
• `category [name]` → run category-specific rubric from `studio-tests/quality-rubric.md`
• `category all` → run category rubric for every skill and every agent that has a `category:` in catalog
• `audit` (or no argument) → read catalog, list all skills and agents, show coverage

If the argument is unrecognized, output usage and stop.

**The old spec folder.** Glob `CCGS Skill Testing Framework/catalog.yaml`. When it exists, say so first: "`CCGS Skill Testing Framework/` was renamed `studio-tests/` in 1.2.0, and this skill reads only `studio-tests/`. Move any specs you wrote there; UPGRADING.md (v1.1.3 → v1.2.0, `studio-tests/`) says how." Then go on with `studio-tests/`.

**Resolve the name before `spec` or `category`.** Look it up in `studio-tests/catalog.yaml`: an entry under `skills:` is a skill (`.claude/skills/[name]/SKILL.md`); an entry under `agents:` is an agent (`.claude/agents/[name].md`). With no catalog entry, use whichever of those two files exists. Only when neither exists, report "'[name]' is neither a skill in `.claude/skills/` nor an agent in `.claude/agents/`." and stop. A name that is also an ordinary word is still a name: `/skill-test spec help` tests the `/next-step` skill, never a request for this skill's usage.

The 7 checks lint SKILL.md structure, so they are skills-only. Given an agent name, `static` runs only the observations below: an agent file has no phases or verdict keywords to lint. Never report the agent as missing.

---

Phase 2A: Static Mode — Structural Linter

For each skill being tested, read its `SKILL.md` and every file in its `references/` folder fully, and run all 7 checks on them as one skill — the longest skills keep each phase in `references/`. The frontmatter checks (1, 6 and 7) read `SKILL.md`.

Check 1 — Required Frontmatter Fields

The file must contain all of these in the YAML frontmatter block:

• `name:`
• `description:`
• `argument-hint:`
• `user-invocable:`
• `allowed-tools:`

**FAIL** if any are absent. A file whose frontmatter does not parse fails Check 1 too — malformed YAML is a structural defect this check exists to catch, not an unassessable file; see the per-skill result rule below.

Check 2 — Multiple Phases

The skill must have ≥2 numbered phase headings. Look for patterns like:

• `## Phase N` or `## Phase N:`
• `## N.` (numbered top-level sections)
• At least 2 distinct `##` headings if phases aren't explicitly numbered

**FAIL** if fewer than 2 phase-like headings are found.

Check 3 — Verdict Keywords

The skill must communicate a clear outcome. Accept any of:

• **Gate / review verdicts** — `PASS`, `FAIL`, `CONCERNS`, `APPROVED`,

`BLOCKED`, `COMPLETE`, `READY`, `COMPLIANT`, `NON-COMPLIANT`

• **Go / no-go verdicts** — `PROCEED`, `PIVOT`, `KILL`, `GO`, `NO-GO`
• **Severity scales** — `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`. Audit skills rank

findings by severity instead of issuing one verdict for the whole run.

**FAIL** if none are present **and** the skill produces an assessment — its description or body promises a review, audit, check, gate, or readiness judgement.

**WARN** (never FAIL) i