# Skill Audit

> |

- **Type:** Skill
- **Install:** `agentstack add skill-wyattjoh-skills-skill-audit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [wyattjoh](https://agentstack.voostack.com/s/wyattjoh)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wyattjoh](https://github.com/wyattjoh)
- **Source:** https://github.com/wyattjoh/skills/tree/main/skills/skill-audit

## Install

```sh
agentstack add skill-wyattjoh-skills-skill-audit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/wyattjoh)
- **Source:** [wyattjoh/skills](https://github.com/wyattjoh/skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wyattjoh-skills-skill-audit
- Seller: https://agentstack.voostack.com/s/wyattjoh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.