skill-auditor

name	skill-auditor
description	Audit agent skills using marketplace-quality heuristics. Performs automated structure analysis, token optimization, routing integrity checks, and content quality assessment. Generates detailed reports with severity-categorized findings and concrete fixes. Use when preparing skills for publication, conducting quality reviews, or when asked to "audit this skill", "review skill quality", "check skill structure", or "validate skill for release".
disable-model-invocation	true
user-invocable	true

Audit Skill

Audit skills against design principles with automated checks and manual audit. Report findings by severity with concrete fixes.

Quick Start

Run automated checks first, then manual review:

./scripts/review-skill.sh <skill-path>

This covers structure, token footprint, routing integrity, and evals presence.

Review Process

Phase 1: Automated Checks

The script validates:

• File structure and SKILL.md existence
• Token footprint with heuristic flags
• Routing integrity (orphans and dangling links)
• Frontmatter completeness

Phase 2: Manual Review

Focus on areas requiring human judgment:

Check	Focus	Reference
Progressive disclosure	Query tracing, reference utilization	Details
Content quality	Hallucination risk, agent ergonomics	Criteria
Description triggering	User language, trigger phrases	Criteria
Redundancy	Cross-file duplication patterns	Detection methods
Advanced checks	Lifecycle and performance	Methods
User experience	Accessibility and usability	Guidelines
Quality metrics	Testing and measurement	Approaches

Phase 3: Reporting

Structure findings by severity and provide concrete fixes. See reporting template.

Anti-Patterns

Pattern	Problem	Solution
Flagging style preferences	Not actionable for skill function	Focus on functional issues only
Vague concerns	No clear fix available	Cite specific files and line numbers
Token budget absolutism	Ignores skill scope reality	Use heuristics as guidance, not rules
Perfect-is-enemy-of-good	Blocks useful skills over minor issues	Prioritize by actual user impact

Output Artifacts

A complete review produces:

1. Automated report - Script output with measurements
2. Manual findings - Severity-categorized issues with specific fixes
3. Progressive disclosure assessment - Query tracing and routing analysis
4. Fix recommendations - Concrete actions with file/line references

Style: respect the repo's conventions

If the target repo or agent uses a caveman skill or any other brevity convention, match that style — produce terser reports without losing technical accuracy. Don't introduce a verbose audit format into a repo whose other agent instructions are deliberately compressed.

What Not to Flag

• Missing optional files unless maintainer requested them
• Token budgets as absolute limits (they're guidance)
• Style preferences unrelated to skill effectiveness
• Minor inconsistencies that don't impact functionality