Skill Audit

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. Include ALL of these details in the agent prompt:

> Analyze the current session for skill execution issues. > > Session file: ~/.claude/projects/!pwd | sed 's|/|-|g'/${CLAUDE_SESSION_ID}.jsonl > > Target skill: $ARGUMENTS > > What to do: > > 1. Run parse-conversation.ts --format=stats on the session file to get a tool call overview > 2. Run parse-conversation.ts --include-tools --format=readable --search="$ARGUMENTS" 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: 

### Summary

### 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

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 /claude-skills 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wyattjoh
• Source: wyattjoh/skills
• License: MIT

Install and usage instructions live in the source repository linked above.