| name | cli-audit |
| description | Use when the user says: "audit this CLI", "CLI quality check", "full CLI review", "CLI UX audit". Comprehensive CLI tool quality audit across all dimensions — hardening, output, clarity, affordances, and complexity. |
| user-invocable | true |
Run a comprehensive quality audit of a CLI tool across all cli-* dimensions. Produces a single prioritized report covering hardening, output design, message clarity, discoverability, and complexity.
Arguments
$ARGUMENTS — path to a CLI script or tool, or blank to target the current branch's changed files.
Phase 1: Discover
Identify what to audit:
- If $ARGUMENTS names a file or directory, scope to that
- Otherwise, find CLI scripts changed on this branch (
git-branch-diff-files | grep -E '\.(sh|bash|py|ts|js)$')
- If no files are found, stop and tell the user: "No CLI scripts found on this branch. Pass a file path as an argument (e.g.,
/cli-audit path/to/script.sh) or run on a branch with CLI file changes."
- Read each file to understand scope and complexity
Phase 2: Audit
Read the REFERENCE.md for each sibling skill. If any file is not found, stop and report the missing path(s) to the user rather than proceeding without reference material.
${CLAUDE_CONFIG_DIR:-~/.claude}/skills/cli-harden/REFERENCE.md — edge-case resilience${CLAUDE_CONFIG_DIR:-~/.claude}/skills/cli-output/REFERENCE.md — output design${CLAUDE_CONFIG_DIR:-~/.claude}/skills/cli-clarify/REFERENCE.md — message clarity${CLAUDE_CONFIG_DIR:-~/.claude}/skills/cli-affordances/REFERENCE.md — discoverability${CLAUDE_CONFIG_DIR:-~/.claude}/skills/cli-distill/REFERENCE.md — complexity
Evaluate the tool against each dimension. Score each area:
- Strong — no significant issues
- Adequate — minor gaps, nothing urgent
- Weak — meaningful gaps that affect usability
- Poor — active problems users will hit
Phase 3: Report
Present a scorecard followed by prioritized findings:
## CLI Audit: <tool name>
| Dimension | Score | Top Finding |
|---------------|----------|--------------------------------|
| Hardening | Strong | — |
| Output | Weak | Tables overflow on narrow terminals |
| Clarity | Adequate | Help text missing examples |
| Affordances | Weak | No tab completion, 3 dead flags|
| Complexity | Strong | — |
Then list all findings grouped by severity (Risk → Gap → Improvement), with file and line references.
Run get-skill-tmpdir cli-audit and write the full scorecard and findings to <tmpdir>/audit-YYYY-MM-DD.md. Tell the user where the file was saved.
AskUserQuestion:
question: "Here's the audit. How would you like to proceed?"
header: "Confirm"
options:
- label: "Fix all"
description: "Address all risks and gaps across every dimension."
- label: "One dimension"
description: "I'll pick which dimension to focus on."
- label: "Let me pick"
description: "I'll choose individual findings to address."
- label: "Stop here"
description: "The audit report is enough — don't change anything."
If "Fix all" → implement all risks + gaps.
If "One dimension" → ask which:
AskUserQuestion:
question: "Which dimension would you like to focus on?"
header: "Dimension"
options:
- label: "Hardening"
description: "Fix edge-case resilience findings only."
- label: "Output"
description: "Fix output design findings only."
- label: "Clarity"
description: "Fix message clarity findings only."
- label: "Affordances"
description: "Fix discoverability findings only."
If the user selects "Other" and types "Complexity", use cli-distill findings. Then implement only that dimension's findings.
If "Let me pick" → present findings individually for accept/reject.
If "Stop here" → end.
Phase 4: Implement
Fix each accepted finding. After all changes:
- Run existing tests if present — detect the runner (
pytest for Python, go test for Go, npm test/jest/vitest for Node/TS, bats for shell). Use timeout 300 on all invocations.
- Verify fixes don't break the happy path
- Summarize changes per dimension
