Claude Skill Audit

gistfile1.txt

Audit my Claude Skills (~/.claude/skills/*/SKILL.md and any project skills) on
five dimensions. For each skill, return: current state -> recommended change ->
one-line why. End with a consolidated changelog grouped by skill.

1. INVOCATION CONTROL (frontmatter)
   Reference: https://code.claude.com/docs/en/skills.md#frontmatter-reference

   - Skills with side effects (deploy, commit, push, send-message, post-to-slack,
     delete, force-push): add `disable-model-invocation: true` so Claude can't
     auto-fire them. User runs them deliberately with /name.
   - Skills that are pure background knowledge with no user-actionable command
     (legacy-system-context, domain glossaries, "how our auth works"): add
     `user-invocable: false` so they don't clutter the / menu. Claude still
     auto-loads them when relevant.
   - Flag any skill where `allowed-tools` grants tools the skill never actually
     uses -- over-permissive allowlists silently widen the auto-approval surface.
   - Flag skills missing `paths` that are clearly project-scoped (e.g. only
     relevant inside a specific repo or file pattern) -- adding `paths` prevents
     irrelevant auto-activation.

2. DESCRIPTION QUALITY (the trigger surface)
   The `description` field is the entire reason Claude decides to load a skill.
   For each skill, judge:
   - Is it specific enough that Claude knows WHEN to use it (not just what it
     does)? Good descriptions name the trigger conditions.
   - Is it short enough to not bloat every conversation? (Descriptions sit in
     context permanently for default-invocable skills.)
   - For user-only skills (`disable-model-invocation: true`), the description
     can be terser since Claude isn't pattern-matching against it.

3. DETERMINISTIC VS NON-DETERMINISTIC STEPS
   Find any step inside a skill body where Claude is interpreting something that
   is actually a fixed, repeatable operation (run these git commands in this
   order, format this output this way, capture screenshots at these viewports).
   Suggest moving those steps into a script in the skill folder that the body
   just invokes. Keep AI for steps that need judgment (writing the commit
   message, deciding what to test, choosing which file to edit).

   Note: this saves AI reasoning tokens and removes nondeterminism, but the
   skill body still loads into context -- so also see audit #4.

4. SKILL BODY SIZE
   Flag any SKILL.md over ~150 lines. Long bodies bloat context every time the
   skill loads. Options:
   - Move reference material into separate files the skill points to
     ("see ./examples/foo.md")
   - Split into multiple smaller skills
   - Use `context: fork` to run the skill in a forked subagent context so the
     body doesn't pollute the main thread

5. COMPOSABILITY
   Flag any skill that duplicates logic another skill already has. Suggest
   extracting shared logic into either (a) a callable script in a shared
   location, or (b) a smaller skill that the others reference. Note: cross-skill
   references work by prose ("see the X skill for Y"), not by import.

OUTPUT
For each skill, show the current frontmatter and the rewritten frontmatter side
by side. Show any prose rewrites as a diff. End with a consolidated changelog:
"skill-name: changed X because Y."

Do NOT modify anything. Just produce the report.