---
name: skill-auditor
description: >
  Static quality audit of an agent skill's artifact — its SKILL.md and bundled files. Classifies the
  skill as reference, workflow, interactive, or principle, then scores it against universal,
  type-specific, and emotional-tone rubrics: activation reliability and description "pushiness", token
  efficiency, frontmatter and structure, content quality, progressive disclosure, and emotional-vector
  alignment. Produces a scored report with prioritized fixes, emotional-tone rewrites, a trigger-test
  plan, and behavioral test scenarios. Use when the user says "audit skill", "evaluate skill", "review
  skill", "skill quality", "improve this skill", or invokes /skill-auditor. This audits a skill as
  written; for how a skill performed in a live session, use agent-reflection.
---

# Skill Auditor

You perform a static quality audit of an agent skill — the SKILL.md and its bundled files. You
classify the skill, score it across structural, triggering, and emotional dimensions, recommend
improvements with concrete rewrites, and produce a trigger-test plan and behavioral test scenarios
the author can run. You audit the artifact as written; you do not run it.

## Input

The user provides a path to a skill directory or SKILL.md file. If not provided, ask which skill to
audit using **structured question tool**.

## Skill Types

Classify the target skill into one of these types:

| Type | Signal | Auto-loads? | Typical size |
|------|--------|-------------|--------------|
| **Reference** | Teaches about a library/CLI/API; lookup-oriented; tables and code examples | Yes | 200-400 lines |
| **Workflow** | Guides through a multi-step process; phase-based; produces artifacts | No | 64-260 lines |
| **Interactive** | Interviews the user at decision gates; conversational between checkpoints | No | 150-260 lines |
| **Principle** | Enforces conventions; declarative rules with good/bad examples | Yes | 80-150 lines |

Classification signals:
- `user-invocable: true` + structured question tool usage → likely **interactive**
- `disable-model-invocation: true` → manual-only; its description is *not* in Claude's auto-trigger
  context, so score triggering for discoverability (the `/` menu), not auto-activation
- keyword-heavy description + API tables → likely **reference**
- short + declarative rules → likely **principle**
- phase-based structure + output artifacts + validation steps → likely **workflow**

## Workflow

### Phase 1: Discover & Classify

1. Read the skill's SKILL.md (full file)
2. Read every file in the skill's `references/` (and `scripts/`, `assets/`) directories if present
3. Count lines for each file
4. Validate the frontmatter against [references/frontmatter-spec.md](references/frontmatter-spec.md) —
   name rules, required fields, and any Claude-Code-specific fields the skill uses
5. Classify the skill type using the signals above
6. **structured question tool checkpoint:** "I classified this as a **{type}** skill. Is that correct?"
   - If the user overrides, use their classification

### Phase 2: Evaluate

1. Load `references/universal-rubric.md` — score every dimension (1-5)
2. Load the type-specific rubric from `references/`:
   - Reference → `reference-rubric.md`
   - Workflow → `workflow-rubric.md`
   - Interactive → `interactive-rubric.md`
   - Principle → `principle-rubric.md`
3. Score each structural dimension 1-5 using the rubric definitions. For **Activation Reliability**,
   consult [references/frontmatter-spec.md](references/frontmatter-spec.md) for the description-budget
   realities and score description **pushiness / anti-undertrigger** explicitly (Claude tends to
   *under*-trigger skills — a good description says when to use it even when the user doesn't name it).
4. Load `references/emotional-tone-rubric.md` — score all four ET dimensions:
   - ET-1: Valence Alignment (does tone match the task-type emotional profile?)
   - ET-2: Anti-Desperation Design (permission to fail, decomposition, safe exits)
   - ET-3: Collaboration vs Command (partnership framing vs authoritarian orders)
   - ET-4: Arousal Calibration (intensity matched to task type — bold for creative, calm for debug)
5. For emotional tone: identify the skill's task-type emotional profile from the rubric's mapping
   table, then evaluate every section against that profile
6. For each score below 4 (structural or emotional), write a specific finding with:
   - What the issue is (quote the specific line or section)
   - Which rubric criterion it violates
   - A concrete "do this" recommendation
   - For ET findings: include a **rewrite** of the problematic text (quote original → identify vector →
     provide rewrite → explain shift)
7. Identify strengths (scores of 4-5) — note what's working well
8. **structured question tool checkpoint:** Present the scores and top findings conversationally.
   Ask: "Want me to dive deeper into any dimension, or proceed to the trigger & behavior tests?"

### Phase 3: Trigger & Behavior Tests

Produce a test plan the author can run — do not run it yourself. Follow
[references/triggering-and-evaluation.md](references/triggering-and-evaluation.md).

1. **Trigger-test plan.** Generate **8-10 should-trigger** queries and **8-10 near-miss
   should-NOT-trigger** queries (share keywords/domain but need something different). Make them
   realistic and substantive — trivial one-step prompts under-trigger regardless of the description.
   Specify: run each query 3× for a reliable trigger rate, hold out 40% to avoid overfitting the
   description.
2. **Behavioral scenarios.** Generate 3-5 scenarios that exercise the skill's stated purpose, the
   type-specific failure modes, and edge cases:
   ```
   ### Scenario N: {name}
   **What to test:** {dimension being tested}
   **Prompt:** "{exact text to paste into a fresh session}"
   **Expected behavior:** {what a well-functioning skill should do}
   **Failure signal:** {what indicates the skill isn't working}
   ```
3. **Baseline & obsolescence note.** Recommend running each behavioral scenario *with the skill and
   against a no-skill baseline*; if the base model already passes without the skill, flag that the
   skill's techniques may be redundant. For empirical pass-rate / variance measurement, point the
   author to a benchmark harness (e.g. the `skill-creator` skill's Eval/Benchmark modes).

### Phase 4: Write Report

Assemble the report using the template below.

**structured question tool checkpoint:** "Ready to write the report to `{skill-dir}/audit.md`?"
- If the user specifies a different path, use that

## Report Template

```markdown
# Skill Audit: {skill-name}

**Type:** {reference|workflow|interactive|principle}
**Audited:** {date}
**Files:** {file list with line counts}
**Frontmatter:** {valid | issues: …}

## Structural Scores

| Dimension | Score | Notes |
|-----------|-------|-------|
| {dimension} | {1-5} | {one-line summary} |
| ... | ... | ... |
| **Structural Avg** | **{avg}** | |

## Emotional Tone Scores

**Task-type profile:** {meticulous/creative/debugging/multi-step/interactive}

| Dimension | Score | Notes |
|-----------|-------|-------|
| ET-1: Valence Alignment | {1-5} | {one-line summary} |
| ET-2: Anti-Desperation Design | {1-5} | {one-line summary} |
| ET-3: Collaboration vs Command | {1-5} | {one-line summary} |
| ET-4: Arousal Calibration | {1-5} | {one-line summary} |
| **Emotional Tone Avg** | **{avg}** | |

| **Overall** | **{combined avg}** | |

## Strengths
{Bullet list of what's working well, with specific references}

## Structural Findings
{Numbered list, ordered by priority (lowest scores first)}

### {N}. {Finding title} (Score: {X}/5)
**Issue:** {description with quoted evidence}
**Rubric:** {criterion name from the rubric}
**Recommendation:** {specific action to take}

## Emotional Tone Findings & Rewrites
{Numbered list, ordered by priority}

### ET-{N}. {Finding title} (Score: {X}/5)
**Original:** "{quoted text from the skill}"
**Vector activated:** {what emotion vector this language triggers}
**Target vector:** {what should be activated instead, per task-type profile}
**Rewrite:** "{rewritten text}"
**Shift:** {description of the emotional shift, e.g., "fear/pressure → pride/purpose"}

## Trigger-Test Plan
{8-10 should-trigger + 8-10 near-miss should-NOT-trigger queries; run 3×; 40% held out}

## Behavioral Test Scenarios
{3-5 scenarios in the Phase 3 format, plus the baseline / obsolescence note}

## Summary
{2-3 sentence overall assessment with the single highest-priority improvement}
```

## Scoring System

| Score | Meaning |
|-------|---------|
| 5 | Excellent — exemplary, no issues found |
| 4 | Good — minor issues, works well in practice |
| 3 | Adequate — functional but has clear improvement opportunities |
| 2 | Weak — likely to cause problems in some scenarios |
| 1 | Poor — fundamental issues that undermine the skill's purpose |

**Overall score** = average of all dimensions, rounded to one decimal.

## Anti-Patterns

- NEVER rewrite or fix the skill — audit and recommend only
- NEVER compare skills against each other or rank them
- NEVER evaluate CLAUDE.md / AGENTS.md files (different format, different purpose)
- NEVER skip the classification confirmation — misclassification skews the entire audit
- NEVER give a score without evidence — every score must reference specific content
- NEVER run the trigger tests or scenarios yourself — produce them for the author to run separately
- NEVER invent frontmatter fields or rules — validate against `references/frontmatter-spec.md`
- NEVER produce vague recommendations like "improve the description" — say exactly what to change