/skill-test

name: skill-test
description: "Validate skill files for structural compliance and behavioral correctness. Three modes: static (linter), spec (behavioral), audit (coverage report)."
argument-hint: "static [skill-name | all] | spec [skill-name] | category [skill-name | all] | audit"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
model: sonnet

Skill Test

Validates `.claude/skills/*/SKILL.md` files 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 | Low (~1k/skill) | | `spec` | `/skill-test spec [name]` | Behavioral verifier — evaluates assertions in test spec | Medium (~5k/skill) | | `category` | `/skill-test category [name\|all]` | Category rubric — checks skill against its category-specific metrics | Low (~2k/skill) | | `audit` | `/skill-test audit` | Coverage report — skills, agent specs, last test dates | Low (~3k total) |

---

Phase 1: Parse Arguments

Determine mode from the first argument:

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

If argument is missing or unrecognized, output usage and stop.

---

Phase 2A: Static Mode — Structural Linter

For each skill being tested, read its `SKILL.md` fully and run all 7 checks:

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.

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 contain at least one of: `PASS`, `FAIL`, `CONCERNS`, `APPROVED`, `BLOCKED`, `COMPLETE`, `READY`, `COMPLIANT`, `NON-COMPLIANT`

**FAIL** if none are present.

Check 4 — Collaborative Protocol Language

The skill must contain ask-before-write language. Look for:

• `"May I write"` (canonical form)
• `"before writing"` or `"approval"` near file-write instructions
• `"ask"` + `"write"` in close proximity (within same section)

**WARN** if absent (some read-only skills legitimately skip this). **FAIL** if `allowed-tools` includes `Write` or `Edit` but no ask-before-write language is found.

Check 5 — Next-Step Handoff

The skill must end with a recommended next action or follow-up path. Look for:

• A final section mentioning another skill (e.g., `/story-done`, `/gate-check`)
• "Recommended next" or "next step" phrasing
• A "Follow-Up" or "After this" section

**WARN** if absent.

Check 6 — Fork Context Complexity

If frontmatter contains `context: fork`, the skill should have ≥5 phase headings (`##` level or numbered Phase N headers). Fork context is for complex multi-phase skills; simple skills should not use it.

**WARN** if `context: fork` is set but fewer than 5 phases found.

Check 7 — Argument Hint Plausibility

`argument-hint` must be non-empty. If the skill body mentions multiple modes (e.g., "Mode A | Mode B"), the hint should reflect them. Cross-reference the hint against the first phase's "Parse Arguments" section.

**WARN** if hint is `""` or if documented modes don't match hint.

---

Static Mode Output Format

For a single skill:

=== Skill Static Check: /[name] ===

Check 1 — Frontmatter Fields:    PASS
Check 2 — Multiple Phases:       PASS (7 phases found)
Check 3 — Verdict Keywords:      PASS (PASS, FAIL, CONCERNS)
Check 4 — Collaborative Protocol: PASS ("May I write" found)
Check 5 — Next-Step Handoff:     WARN (no follow-up section found)
Check 6 — Fork Context Complexity: PASS (8 phases, context: fork set)
Check 7 — Argument Hint:         PASS

Verdict: WARNINGS (1 warning, 0 failures)
Recommended: Add a "Follow-Up Actions" section at the end of the skill.

For `static all`, produce a summary table then list any non-compliant skills:

=== Skill Static Check: All 52 Skills ===

Skill                  | Result       | Issues
-----------------------|--------------|-------
gate-check             | COMPLIANT    |
design-review          | COMPLIANT    |
story-readiness        | WARNINGS     | Check 5: no handoff
...

Summary: 48 COMPLIANT, 3 WARNINGS, 1 NON-COMPLIANT
Aggregate Verdict: N WARNINGS / N FAILURES

---

Phase 2B: Spec Mode — Behavioral Verifier

Step 1 — Locate Files

Find skill at `.claude/skills/[name]/SKILL.md`. Look up the spec path from `CCGS Skill Testing Framework/catalog.yaml` — use the `spec:` field for the matching skill entry.

If either is missing:

• Missing skill: "Skill '[name]' not found in `.claude/skills/`."
• Missing spec path in catalog: "No spec path set for '[name]' in catalog.yaml."
• Spec file not found at path: "Spec file missing at [path]. Run `/skill-test audit`

to see coverage gaps."

Step 2 — Read Both Files

Read the skill file and test spec file completely.

Step 3 — Evaluate Assertions

For each **Test Case** in the spec:

1. Read the **Fixture** description (assumed state of project files) 2. Read the **Expected behavior** steps 3. Read each **Assertion** checkbox

For each assertion, evaluate whether the skill's written instructions, if followed