skill-audit

name	skill-audit
description	Audit skills for quality, structure, and efficiency. Finds deterministic steps that should be scripts, duplicated logic across skills, composability gaps, and weak descriptions. Run after creating or updating any skill, or when the user says "audit my skills", "review my skills", "check skill quality", "is this skill good", or "improve my skills".

Skill Audit

Scan skills, then apply judgment to identify what should change and why. The script does detection - you do the decisions.

Input

• $ARGUMENTS (optional) - a specific skill name to audit in focused mode. Omit to audit all skills.

Step 1 - Scan

~/.claude/commands/skill-audit/scripts/scan-skills.sh $ARGUMENTS

If $ARGUMENTS is empty, scans all skills. If a skill name is provided, scans only that skill (faster, used automatically after creation).

Step 2 - Analyze

Work through each section of the scan output:

---

Deterministic Step Audit

From INLINE_BASH_COMMANDS and BASH_BLOCKS_PER_SKILL:

For each bash block, classify the operation:

Classification	What it looks like	Verdict
Calls an existing script	~/.claude/commands/*/scripts/*.sh	Correct - no change
Pure data collection	cat, ls, find, grep, uname, df, free, ssh + read-only	Extract to script
Text transformation	sed, awk, cut, tr with no conditionals	Extract to script
Conditional / judgment	if/then, case, comparisons, decisions	Keep in SKILL.md
Complex pipeline	>5 piped commands doing what a script would do	Extract to script

For every deterministic block: show BEFORE (the inline block) and AFTER (what the extracted script would look like). Label clearly.

Shared Script Opportunities

From SHARED_SCRIPT_OPPORTUNITIES:

For each match: the skill has inline bash that already exists as a script in another skill. Suggest calling that script directly instead. Name which skill owns it and what the call would look like.

Composability Audit

From DUPLICATE_COMMANDS and the full skill set:

• Does any skill re-implement data collection that another skill's script already provides?
• Could any skill call another skill's script instead of duplicating the logic?
• Are there skills that should chain (one's output is another's input)?

For each duplication: name both skills, show the duplicated lines, suggest which one should own a shared script.

Structure Audit

From SKILL_STRUCTURES:

Flag any skill that:

• Has inline bash blocks but no scripts/ folder - extraction candidate
• Has a scripts/ folder but SKILL.md still has inline data collection - incomplete extraction
• Is a flat .md file (not a folder) - needs migration to folder format

Description Quality

From DESCRIPTION_LENGTHS:

• Under 80 chars: likely too short to trigger reliably
• Missing trigger phrases ("use when the user says...")
• Missing both what-it-does AND when-to-use - both are required for reliable triggering

Missing Metadata

From MISSING_ARGUMENT_HINTS:

Flag any skill using $ARGUMENTS without argument-hint in frontmatter.

---

Step 3 - Output

For each issue found:

SKILL: <name>
ISSUE: <what's wrong, one sentence>
SEVERITY: high | medium | low
BEFORE:
  <the current inline bash block or current description>
AFTER:
  <the extracted script content or improved description>
WHY: <the reason - reuse, token savings, trigger reliability, etc.>

Group by severity. High = duplicated logic, broken triggering, or token waste. Medium = extraction opportunity. Low = description polish.

Summary Table after all issues:

Skill	Extract to Script	Shared Script	Description	Total

Action List at the end - the 3 highest-value changes to make now, in order.