health-agentic-audit

/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.

When to Use This Skill

Use this skill when...	Use another approach when...
Auditing skills for agentic optimization compliance	General plugin audit (use /health:audit)
Finding missing Agentic Optimizations tables	Comprehensive environment check (use /health:check)
Reviewing CLI command patterns in skills	Plugin registry issues (use /health:plugins)
Quality-checking skill documentation	Manual skill review preferred
Batch-updating skill quality standards	Single skill needs updating

Context

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

Parameters

Parameter	Description
--fix	Add skeleton Agentic Optimizations tables to flagged skills and update modified dates
--verbose	Show all scanned files and detailed pattern matching results

Execution

Execute this agentic output audit:

Step 1: Discover all plugin content files

Find all skills, commands, and agents in the codebase:

1. Scan for skills: find . -name 'SKILL.md' -o -name 'skill.md'
2. Scan for all skill variants: find . \( -name 'SKILL.md' -o -name 'skill.md' \)
3. Scan for agents: find . -path '*/agents/*.md' -not -name 'README.md'

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

Step 2: Check each skill for Agentic Optimizations tables

For each skill file:

1. Search for a heading matching ## Agentic Optimization (with or without trailing "s")
2. Search for bash/shell code blocks (```bash or ```sh)
3. Flag skills that have bash code blocks but lack the Agentic Optimizations table

Skip skills without any bash code blocks (informational skills). Note them in verbose mode.

Step 3: Scan for bare CLI commands missing compact flags

Read execution and context sections of all files. Match commands against the bare CLI patterns in REFERENCE.md.

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

Step 4: Check frontmatter dates for staleness

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

Step 5: Generate the audit report

Output a structured markdown report with these sections:

1. Missing Agentic Optimizations Tables — list skills with bash blocks but no table
2. Bare CLI Commands — list commands missing optimization flags with file, line, command, and suggested fix
3. Context Section Issues — context commands using cat or verbose output
4. Stale Reviews (>90 days) — files with outdated modified dates
5. Summary — total counts for skills/commands/agents scanned and issues found

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

Step 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 end of file). Use the skeleton template from REFERENCE.md. 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 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:]]*//'

Agentic Optimizations

Context	Command
Agentic audit scan	/health:agentic-audit
Audit with auto-fix	/health:agentic-audit --fix
Verbose output	/health:agentic-audit --verbose
Find all skill files	find . \( -name 'SKILL.md' -o -name 'skill.md' \) 2>/dev/null
Check for Agentic Optimizations table	grep -l "## Agentic Optimizations" $(find . -name 'SKILL.md') 2>/dev/null

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