Agent Skills: Command Auditor

Reference Files

Command validation guidance (official requirements + custom best practices):

Quick Start:

• INDEX.md - Start here: Navigation guide mapping use cases to reference files
• audit-checklist.md - Quick validation checklist for rapid reviews
• audit-workflow-steps.md - Complete 7-step audit process

Detailed Validation:

• frontmatter-validation.md - Official Anthropic frontmatter features and validation rules (OFFICIAL)
• simplicity-enforcement.md - Simplicity vs complexity assessment and skill migration criteria (GUIDELINES)
• argument-handling.md - Argument parsing patterns and default value validation (BEST PRACTICE)
• documentation-proportionality.md - Documentation level appropriateness (minimal vs full) (BEST PRACTICE)

Common Issues & Reporting:

• common-issues-and-antipatterns.md - 9 frequent issues with examples and fixes
• report-format.md - Standardized audit report structure and template
• examples.md - Good vs poor command comparisons and full audit reports

Official Requirements vs Custom Best Practices

This auditor validates both official Anthropic requirements and custom best practices:

Official Anthropic Requirements (from Claude Code documentation):

• Frontmatter features: description (required), argument-hint, allowed-tools, model, disable-model-invocation (optional)
• Command patterns: Standalone prompts OR bash execution (!) OR file references (@)
• Multiple valid patterns: Commands can provide inline instructions for various purposes
• No official line count limits: Simplicity is conceptual, not numeric

Custom Best Practices (recommended patterns from this codebase):

• Simplicity guidelines: 6-15 lines (simple), 25-80 lines (documented) - guidelines not hard limits
• Documentation proportionality: Match documentation level to command complexity
• Single responsibility: One clear purpose per command
• Argument handling: Use arguments effectively in command instructions

Audit reports will distinguish between violations of official requirements (CRITICAL) and deviations from custom best practices (IMPORTANT or NICE-TO-HAVE).

Command Auditor

Validates command configurations for delegation clarity, simplicity, and documentation proportionality.

Quick Start

New to command auditing? Start with INDEX.md for navigation guidance.

For quick validation: Use audit-checklist.md

For comprehensive audit: Follow the 6-step process in audit-workflow-steps.md:

1. Read command file
2. Validate frontmatter features (description required, optional fields valid)
3. Identify command pattern (standalone prompt, bash, file reference)
4. Assess simplicity guidelines (6-15 simple, 25-80 documented)
5. Validate argument handling
6. Check documentation proportionality and generate audit report

Common issues? See common-issues-and-antipatterns.md for 9 frequent problems with fixes.

Command-Specific Validation

Simplicity Guidelines

File size guidelines (not hard limits):

• 6-15 lines: Typical simple command (frontmatter + minimal content)
• 25-80 lines: Typical documented command (frontmatter + docs + content)
• >80 lines: Consider skill migration (evaluate complexity)

Complexity indicators:

• Line count >80
• Multiple tool calls
• If/else logic
• Loop constructs
• Extensive processing

Argument Handling

Patterns:

Pass-through:

{Task prompt="$ARGUMENTS"}

With defaults:

{Task prompt="${ARGUMENTS:-default value}"}

Positional:

{Task prompt="File: $1, Action: $2"}

Validation:

• Arguments are used (not ignored)
• Defaults make sense
• Usage documented (for documented commands)

Documentation Proportionality

Simple commands: Minimal docs

• Name and description in frontmatter
• Optional: One-line explanation
• No usage section, no examples

Documented commands: Full docs

• Name and description in frontmatter
• Usage section with syntax
• "What It Does" explanation
• Examples section
• Optional: Tips or notes

Rule: Documentation should match complexity

See documentation-proportionality.md for detailed guidelines and examples.

Integration with audit-coordinator

Invocation pattern:

User: "Audit my command"
→ audit-coordinator invokes audit-command
→ audit-command performs specialized validation
→ Results returned to audit-coordinator
→ Consolidated with evaluator findings

Sequence:

1. audit-command (primary) - Command-specific validation
2. evaluator (secondary) - General structure validation

Report compilation:

• audit-command findings (simplicity, arguments, docs, structure)
• evaluator findings (frontmatter, markdown, general validation)
• Unified report with reconciled priorities

Examples

For complete command examples and full audit reports, see examples.md.

Quick examples:

• Good command: Simple command (8-15 lines, clear purpose, proper arguments, minimal docs)
• Needs work: 95-line command with unclear purpose, ignored arguments, excessive docs

Each example in the reference file includes status, findings, scores, and specific fixes.

For detailed guidance on each validation area, consult the reference files linked at the top of this document.