Skill Audit

Post-execution forensics for Claude Code skills. Analyzes the current session's conversation history to find permission denials, tool errors, user corrections, and unexpected behavior during a skill invocation, then offers to fix the skill.

Phase 1: Validate Arguments

Skill name: $ARGUMENTS

If $ARGUMENTS is empty, ask the user which skill they want to audit using AskUserQuestion.

Resolve the skill definition by searching for the SKILL.md file:

1. Use Glob to search skills/*/SKILL.md in the current working directory
2. Also search ~/.claude/skills/*/SKILL.md for installed skills
3. Match the skill name against the directory name (e.g., $ARGUMENTS = just matches skills/just/SKILL.md)

If no matching skill is found, report the error and list available skills so the user can pick one.

Phase 2: Read Target Skill Definition

Read the matched SKILL.md file and extract:

• allowed-tools: What tools the skill is permitted to use (if unrestricted, note that)
• description: Trigger phrases and purpose
• context: Whether it runs forked or inline
• disable-model-invocation: Whether it's manual-only
• Body content: The workflow steps, phases, and instructions the skill defines

Summarize what the skill is supposed to do in 2-3 sentences. This becomes the baseline for detecting deviations.

Phase 3: Delegate Session Analysis

Spawn a conversation-historian agent via the Agent tool with the following prompt, every detail intact:

Analyze the current session for skill execution issues.

Session file: ~/.claude/projects/!pwd | sed 's|[^A-Za-z0-9]|-|g'/${CLAUDE_SESSION_ID}.jsonl

Target skill: $ARGUMENTS

What to do:

1. Run the stats command for the session to get a tool call overview
2. Run the search command with --in=all and the skill name to find the skill invocation point and surrounding context
3. Search for these signals in messages AFTER the skill invocation:
   • Permission denials: tool_result entries with is_error: true, search for "permission", "denied", "not allowed"
   • Tool errors: Any tool_result with is_error: true (failed Bash commands, Read errors, etc.)
   • User corrections: User messages containing "no", "wrong", "instead", "don't", "that's not", "actually", "stop", "I said", "not what I"
   • Retries: The same tool being called multiple times with similar arguments (indicates struggling)
4. Compare actual tool usage against the skill's allowed-tools list: ALLOWED_TOOLS_PLACEHOLDER
   • Flag any tools used that aren't in the allowed list
   • Flag any tools in the allowed list that were denied
5. Return a structured summary with these sections:
   • Permission Denials: List each denial with the tool name and what was attempted
   • Tool Errors: List each error with the tool, arguments summary, and error message
   • User Corrections: List each correction with the user's words and what Claude was doing wrong
   • Unexpected Tool Usage: Tools used outside the allowed-tools list
   • Retries/Struggles: Tools called 3+ times with similar arguments
   • Overall Assessment: 1-2 sentence summary of how well the skill executed

Replace ALLOWED_TOOLS_PLACEHOLDER with the actual allowed-tools value from Phase 2 (or "unrestricted" if none).

Phase 4: Present Findings

Once the conversation-historian returns its analysis, present the findings in a structured format:

Report Structure

## Skill Audit: <skill-name>

### Summary
<Overall assessment from the historian>

### Findings

#### Permission Denials
| Tool | Attempted Action | Recommendation |
|------|-----------------|----------------|
| ...  | ...             | Add to allowed-tools / Adjust skill workflow |

#### Tool Errors
| Tool | Error | Recommendation |
|------|-------|----------------|
| ...  | ...   | Fix path/args in skill body |

#### User Corrections
| What User Said | What Claude Was Doing | Recommendation |
|----------------|----------------------|----------------|
| ...            | ...                  | Revise workflow step |

#### Unexpected Tool Usage
| Tool | Context | Recommendation |
|------|---------|----------------|
| ...  | ...     | Add to allowed-tools or remove from workflow |

### Recommendation Summary
<Numbered list of specific changes to make to the SKILL.md>

If no issues are found in a category, omit that section entirely rather than showing an empty table.

If no issues are found at all, report that the skill executed cleanly and no changes are needed.

Phase 5: Offer Repair

After presenting findings, if there are actionable recommendations:

1. Ask the user if they want to fix the skill now using AskUserQuestion
2. If yes, invoke EnterPlanMode to plan the fixes
3. In the plan, reference /skills-skill for current skill authoring best practices
4. The plan should address each recommendation from Phase 4

If the user declines, suggest they can run /skill-audit $ARGUMENTS again after making manual changes to verify the fixes.