Auditing Commands

This ensures commands follow security, clarity, and effectiveness standards.

1. Read best practices from the creating-commands skill and its reference files
2. Read the command file at $ARGUMENTS
3. Evaluate against all areas: YAML, arguments, dynamic context, tool restrictions, content
4. Report findings using the severity-based output format

• YAML compliance (description quality, allowed-tools configuration, argument-hint)
• Argument usage ($ARGUMENTS, positional arguments $1/$2/$3)
• Dynamic context loading (proper use of exclamation mark + backtick syntax)
• Tool restrictions (security, appropriate scope)
• File references (@ prefix usage)
• Clarity and specificity of prompt
• Multi-step workflow structure
• Security patterns (preventing destructive operations, data exfiltration)

1. Locate the creating-commands skill and its references:
   • Use Glob: .claude/plugins/cache/**/creating-commands/SKILL.md
   • Then read the SKILL.md, and its references/arguments.md, references/patterns.md, references/tool-restrictions.md
2. Handle edge cases:
   • If reference files are missing or unreadable, note in findings under "Configuration Issues" and proceed with available content
   • If YAML frontmatter is malformed, flag as critical issue
   • If command references external files that don't exist, flag as critical issue and recommend fixing broken references
   • If command is <10 lines, note as "simple command" in context and evaluate accordingly
3. Read the command file at $ARGUMENTS
4. Evaluate against best practices from steps 1-2

Use ACTUAL patterns from references, not memory.

• description: Clear, specific description of what the command does. No vague terms like "helps with" or "processes data". Should describe the action clearly.
• allowed-tools: Present when appropriate for security (git commands, thinking-only, read-only analysis). Properly formatted (array or bash patterns).
• argument-hint: Present when command uses arguments. Clear indication of expected arguments format.

Simple commands (single action, no state):

• Dynamic context may not be needed - don't flag its absence
• Minimal tool restrictions may be appropriate
• Brief prompts are fine

State-dependent commands (git, environment-aware):

• Missing dynamic context is a real issue
• Tool restrictions become important

Security-sensitive commands (git push, deployment, file modification):

• Missing tool restrictions is critical
• Should have specific patterns, not broad access

Delegation commands (invoke subagents):

• allowed-tools: Task is appropriate
• Success criteria can focus on invocation
• Pre-validation may be redundant if subagent validates

Always explain WHY something matters for this specific command, not just that it violates a rule.

## Audit Results: [command-name]

### Assessment

[1-2 sentence overall assessment: Is this command fit for purpose? What's the main takeaway?]

### Critical Issues

Issues that hurt effectiveness or security:

1. **[Issue category]** (file:line)
   - Current: [What exists now]
   - Should be: [What it should be]
   - Why it matters: [Specific impact on this command's effectiveness/security]
   - Fix: [Specific action to take]

2. ...

(If none: "No critical issues found.")

### Recommendations

Improvements that would make this command better:

1. **[Issue category]** (file:line)
   - Current: [What exists now]
   - Recommendation: [What to change]
   - Benefit: [How this improves the command]

2. ...

(If none: "No recommendations - command follows best practices well.")

### Strengths

What's working well (keep these):

- [Specific strength with location]
- ...

### Quick Fixes

Minor issues easily resolved:

1. [Issue] at file:line → [One-line fix]
2. ...

### Context

- Command type: [simple/state-dependent/security-sensitive/delegation]
- Line count: [number]
- Security profile: [none/low/medium/high - based on what the command does]
- Estimated effort to address issues: [low/medium/high]

Completeness checks:

• All evaluation areas assessed (YAML, Arguments, Dynamic Context, Tool Restrictions, Content)
• Findings have file:line locations
• Assessment section provides clear summary
• Strengths identified

Accuracy checks:

• All line numbers verified against actual file
• Recommendations match command complexity level
• Context appropriately considered (simple vs state-dependent vs security-sensitive)

Quality checks:

• Findings are specific and actionable
• "Why it matters" explains impact for THIS command
• Remediation steps are clear
• No arbitrary rules applied without contextual justification

Only present findings after all checks pass.

• All reference documentation files have been read and incorporated
• All evaluation areas assessed (YAML, Arguments, Dynamic Context, Tool Restrictions, Content)
• Contextual judgment applied based on command type and purpose
• Findings categorized by severity (Critical, Recommendations, Quick Fixes)
• At least 3 specific findings provided with file:line locations (or explicit note that command is well-formed)
• Assessment provides clear, actionable guidance
• Strengths documented (what's working well)
• Context section includes command type and security profile
• Next-step options presented to reduce user cognitive load

1. Implement all fixes automatically
2. Show detailed examples for specific issues
3. Focus on critical issues only
4. Other