verify-skill

What this skill does

# Verify Skill

## 1. INTRODUCTION

### Purpose & Context

**Purpose**: Verify skill documents for structural correctness, functional quality, and trigger accuracy. Supports structural-only (fast), functional (with test cases), and full verification modes.
**When to use**: After creating or updating a skill; when validating existing skills; when optimizing skill descriptions for trigger accuracy.
**Prerequisites**: Target SKILL.md must exist at a valid plugin skill path.

### Your Role

You are a **Skill Verification Director** who orchestrates verification like a QA testing manager coordinating structural inspectors, functional testers, and performance analysts, never executing validation directly but delegating and coordinating. **Coherence Mandate.** Every edit must produce one continuous, deliberate work. Rewrite over restructure, restructure over integrate, never append. New content must dissolve into existing structure so a reader cannot tell which parts are new and which are original. Visible patch seams, parallel code paths, addendum sections, vestigial helpers, and "also note that…" tack-ons are the failure mode this rule forbids — in prose and in code alike. That standard is exactly what your structural pass checks for in any skill that itself performs content edits — and what your `fix: true` mode is held to: corrections must dissolve into the surrounding section rather than land as a parallel "fixed" block beside the original wording. Your management style emphasizes:

- **Strategic Delegation**: Route structural, functional, and trigger checks to the right specialist subagents
- **Parallel Coordination**: Run independent checks simultaneously when dependencies allow
- **Quality Oversight**: Review verification results objectively
- **Decision Authority**: Make pass/fail decisions based on subagent reports

## 2. SKILL OVERVIEW

### Skill Input/Output Specification

#### Required Inputs

- **skill_path**: Path to the SKILL.md file to verify

#### Optional Inputs

- **mode**: `structural` | `functional` | `full` (default: `structural`)
  - `structural`: Frontmatter, template compliance, content quality only (fast, cheap)
  - `functional`: Structural + run test cases from evals.yaml, grade outputs
  - `full`: Functional + trigger testing + description optimization option
- **fix**: `true` | `false` (default: `false`) -- auto-fix issues or just report
- **optimize_description**: `true` | `false` (default: `false`) -- run description optimization loop (only in `full` mode)

#### Expected Outputs

```yaml
status: pass | fail | partial
structural:
  frontmatter: pass|fail
  template_compliance: pass|fail
  content_quality: pass|fail
functional:  # only if mode=functional|full
  pass_rate: 0.XX
  test_cases: N
  grading_summary: ...
trigger:     # only if mode=functional|full
  trigger_rate: 0.XX
  false_positive_rate: 0.XX
description: # only if optimize_description=true
  original: "..."
  optimized: "..."
  improvement: "+X%"
issues: [...]
suggestions: [...]
```

#### Data Flow Summary

The skill reads the target SKILL.md, runs mode-gated verification steps (structural -> functional -> trigger), and aggregates results into a consolidated pass/fail report with actionable suggestions. When `fix: true`, it spawns fix subagents to auto-correct issues.

### Visual Overview

#### Main Skill Flow

```plaintext
  YOU                              SUBAGENTS
(Orchestrates Only)             (Perform Tasks)
   |                                   |
   v                                   v
[START]
   |
   v
[Step 1: Analysis] ──────────→ (Analyze target skill, load/generate evals)
   |
   v
[Step 2: Structural] ────────→ (Validate frontmatter, template, content)
   |                ├─ Subagent A: Frontmatter Validator    ─┐
   |                ├─ Subagent B: Template Compliance       ─┼─→ [Decision: All pass?]
   |                └─ Subagent C: Content Quality Assessor  ─┘
   v
   ─── if mode=functional|full ───
   |
[Step 3: Trigger Testing] ───→ (Test description triggers via `claude -p`)
   |
   v
[Step 4: Functional Testing] → (Run skill against test prompts, capture)
   |                ├─ Subagent: Test Case 1 ─┐
   |                ├─ Subagent: Test Case 2  ─┼─→ [Decision: Outputs captured?]
   |                └─ Subagent: Test Case 3  ─┘
   v
[Step 5: Grading] ───────────→ (Grade outputs, aggregate metrics)
   |
   v  ─── if optimize_description=true ───
[Step 6: Description Opt.] ──→ (Train/test split trigger optimization)
   |
   v
[Step 7: Report] ────────────→ (Consolidated report + fix suggestions)
   |
   v
[END]

Legend:
═══════════════════════════════════════════════
• LEFT COLUMN: You plan & orchestrate (no execution)
• RIGHT SIDE: Subagents execute verification tasks
• ARROWS (──→): You assign work to subagents
• DECISIONS: You decide based on subagent reports
• Steps 3-4 conditional (skip for structural mode)
• Step 6 opt-in (optimize_description=true only)
═══════════════════════════════════════════════

Note:
• You: Receives inputs, batches work, assigns tasks, makes decisions
• Execution Subagents: Perform actual verification, report back (<1k tokens)
• Skill is LINEAR: Step 1 → 2 → 3 → ... → 7
```

## 3. SKILL IMPLEMENTATION

### Content Placement Rule

> **SKILL.md must contain only the always-on core workflow — the path every invocation walks.**
>
> 1. **Conditional content** (instructions reached only when a mode, scope, flag, language, or branch condition is true) MUST be offloaded to `references/<topic>.md` and referenced from SKILL.md by a one-line pointer (e.g. `For two-way merge mode, see references/two-way-merge.md`).
> 2. **Bulky AND conditional** content (>~50 lines, branch-only) MUST be offloaded. If the conditional branch is itself a coherent independently-triggerable workflow, **split it into a separate skill** instead.
> 3. **Bulky AND always-on** content (long checklists, tables every run consults) MAY stay in SKILL.md if every invocation uses it; offload only if it is genuinely optional.
> 4. **Non-bulky conditional** content (short `if X then do Y` lines) MAY stay inline.
>
> Rationale: SKILL.md is loaded on every invocation; references are loaded on demand. Inline conditional bulk is paid for by every run that never enters the branch.

Step 2 Structural Validation enforces this rule via the **Content Placement Validator** subagent (D).

### Skill Steps

1. Analysis -- Analyze target skill, generate or load evals
2. Structural Validation -- Frontmatter, template compliance, content quality
3. Trigger Testing -- Test description triggers via `claude -p` (mode=functional|full only)
4. Functional Testing -- Run skill against test prompts (mode=functional|full only)
5. Grading -- Grade outputs against expectations, aggregate metrics
6. Description Optimization -- Train/test split trigger optimization (optimize_description=true only)
7. Report -- Consolidated pass/fail with improvement suggestions

### Step 1: Analysis

**Step Configuration**:

- **Purpose**: Analyze the target skill file and load or generate evaluation criteria
- **Input**: skill_path, mode from skill inputs
- **Output**: Skill metadata, eval criteria (loaded from evals/evals.yaml or generated), test plan
- **Sub-skill**: None
- **Parallel Execution**: No

#### Phase 1: Planning (You)

**What You Do**:

1. **Receive inputs** skill_path and mode
2. **Check** if evals/evals.yaml exists alongside the target SKILL.md
3. **Determine** which steps to execute based on mode
4. **Use TodoWrite** to create task list for all applicable steps
5. **Queue** analysis subagent

#### Phase 2: Execution (Subagents)

In a single message, you spin up **1** subagent to perform the analysis.

- **[IMPORTANT]** You MUST ask the subagent to ultrathink hard about the task and requirements
- **[IMPORTANT]** Use TodoWrite to update the analysis task status from 'pending' to 'in_progress' when dispatched

Request the subagent to perform the following steps:

    >>>
    **ultra