Skill audit

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.