/health:agentic-audit

Scan all plugin skills, commands, and agents for CLI output optimization opportunities. Checks for missing Agentic Optimizations tables, bare CLI commands without compact flags, and stale review dates.

Standards reference: .claude/rules/agentic-optimization.md and .claude/rules/skill-quality.md.

Context

• Plugin root: !pwd
• Skill files: !find . -name 'SKILL.md' -o -name 'skill.md' 2>/dev/null
• Skill files (all): !find . \( -name 'SKILL.md' -o -name 'skill.md' \) 2>/dev/null
• Agent files: !find . -path '*/agents/*.md' -not -name 'README.md' 2>/dev/null

Parameters

Workflow

Phase 1: Discover Files

Find all plugin content files:

1. Skills: find . -name 'SKILL.md' -o -name 'skill.md'
2. Skills (all): find . \( -name 'SKILL.md' -o -name 'skill.md' \)
3. Agents: find . -path '*/agents/*.md' -not -name 'README.md'

Classify each file by type (skill, command, agent) for the report.

Phase 2: Check for Agentic Optimizations Tables

For each skill file:

1. Check if it contains a heading matching ## Agentic Optimization (with or without trailing “s”)
2. Check if it contains bash/shell code blocks (```bash or ```sh)
3. Flag skills that have bash code blocks but lack the Agentic Optimizations table

Skills without any bash code blocks are informational and can be skipped (note them in verbose mode).

Phase 3: Check for Bare CLI Commands

Scan execution and context sections of all files for commands missing compact/machine-readable flags.

Search for these patterns inside fenced code blocks and backtick context commands (! backtick syntax).

Phase 4: Check Frontmatter Dates

For each file, extract the modified date from YAML frontmatter:

1. Parse modified: YYYY-MM-DD from the first 20 lines
2. Calculate days since modification
3. Flag files where modified is older than 90 days as stale

Phase 5: Generate Report

Output a structured markdown report:

## Agentic Output Audit Report

### Missing Agentic Optimizations Tables
| File | Plugin | CLI Tools Detected |
|------|--------|--------------------|
(List skills with bash blocks but no table)

### Bare CLI Commands (no compact flags)
| File | Line | Command | Suggested Fix |
|------|------|---------|---------------|
(List commands missing optimization flags)

### Context Section Issues
| File | Line | Issue | Fix |
|------|------|-------|-----|
(Context commands using cat or verbose output)

### Stale Reviews (>90 days)
| File | Last Modified | Days Stale |
|------|---------------|------------|

### Summary
- X skills scanned, Y commands scanned, Z agents scanned
- N missing Agentic Optimizations tables
- M bare CLI commands found
- P context section issues
- Q stale reviews

If --verbose: also list all scanned files with their status (pass/fail per check).

Phase 6: Apply Fixes (if –fix)

When --fix is passed:

1. Add skeleton Agentic Optimizations tables to flagged skills:

   • Insert before the last heading or at the end of the file
   • Use this template:

     ## Agentic Optimizations
     
     | Context | Command |
     |---------|---------|
     | Quick check | `TODO: add compact command` |
     | CI mode | `TODO: add CI-friendly command` |
     | Errors only | `TODO: add errors-only command` |
     

   • Leave TODO entries for the user to fill in

2. Update modified date in frontmatter of each modified file to today’s date

3. Report changes: Show which files were modified and what was added

Prompt the user to fill in the TODO entries with actual optimized commands.

Pattern Detection Details

Code Block Detection

Match fenced code blocks to identify CLI tools:

```bash
<command>

And inline backtick commands in context sections:

• Label: !<command>

### Frontmatter Extraction

Use the standard extraction pattern:
```bash
head -20 "$file" | grep -m1 "^modified:" | sed 's/^[^:]*:[[:space:]]*//'

See Also

• /health:check – Full diagnostic scan
• /health:audit – Plugin relevance audit
• .claude/rules/agentic-optimization.md – Optimization standards
• .claude/rules/skill-quality.md – Required skill sections