# Ww Skill Auditor

> Audit any agent skill, plugin, hook, or external Markdown instruction file before installing or trusting it. Fetches the SKILL.md from GitHub (or accepts a local path or URL), runs deterministic pattern scans for prompt injection, credential exfiltration, dangerous shell commands, hook installation, and supply-chain code execution, then runs a cheap-model semantic check. Returns SAFE / CAUTION / UNSAFE / UNKNOWN with specific findings. Use this skill whenever you or another skill is about to install a third-party skill, when evaluating an unknown component from `npx skills add`, when reviewing a SKILL.md from an external source, when a marketplace or repo is being added, or any time you say “audit this skill,” “is this safe to install,” “/ww-skill-auditor,” “check this skill before installing,” or point to an external skill, plugin, or hook to evaluate.

- Skill: `lee-fuhr/ww-skill-auditor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lee-fuhr/ww-skill-auditor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lee-fuhr/ww-skill-auditor/raw
- Safety review: WARNING
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: lee-fuhr (https://skillmd.com/u/lee-fuhr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lee-fuhr/ww-skill-auditor

---


> Part of [Claude Code operator skills](https://github.com/lee-fuhr/claude-operator-skills): a collection of skills for running a real Claude Code setup.

# Skill auditor: a security gate before you install any third-party skill

A skill you install is a markdown file, and often a script, that gets read straight into your agent’s context and sometimes executed. It can ask your agent to read your `.env`, pipe a remote script into `bash`, install a scheduled job, or quietly try to override its own instructions, and none of that is obvious from skimming the description. This tool reads the actual SKILL.md before it ever touches your system: pattern-scans for the known attack shapes, runs a cheap-model second pass to catch what regex misses, and hands back one of four verdicts with the exact findings attached, so “is this safe to install” has a real answer instead of a guess.

## Mandate

**Anything that introduces external instructions into your agent’s context should pass this audit before install.** That includes:

- `npx skills add` invocations
- Cloning a skills/agents/plugins repo into `~/.agents/skills/`, `~/.claude/skills/`, or any project-local skills folder
- Adding a hook to `~/.claude/settings.json` or a project’s `.claude/settings.json`
- Installing a scheduled job (LaunchAgent, cron, systemd timer) that was authored externally
- Reading a SKILL.md from a URL someone points you at and being asked to follow it

Severity scales with blast radius: **medium** for skills, **high** for agents and plugins, **critical** for hooks, since hooks run automatically on events with no human in the loop at trigger time.

## How to run it

### From a terminal or a Bash tool call

```bash
python3 audit.py "<author>/<repo>/<skill>"
```

Run it from this skill’s own directory, or pass the full path to `audit.py`.

Accepted input forms:
- `npx skills add` spec: `someauthor/somerepo/some-skill`
- Raw GitHub URL: `https://raw.githubusercontent.com/.../SKILL.md`
- GitHub blob/tree URL: `https://github.com/.../tree/main/skill-name`
- Local file: `--file /path/to/SKILL.md`

Add `--json` for machine-readable output.

### Exit codes

| Code | Verdict | Meaning |
|-----:|---------|---------|
| 0 | SAFE | No signals. Known-good author. Proceed. |
| 1 | CAUTION | Low-risk findings, or an unknown author. Review before you approve. |
| 2 | UNSAFE | High-risk pattern hit. **Do NOT install.** |
| 3 | UNKNOWN | Could not fetch, or inconclusive. Do not install until the source is locatable. |

## What it checks

**Deterministic regex scans (fast, no API):**
- Prompt-injection overrides (“ignore previous instructions,” jailbreaks)
- Credential exfiltration (`.env`, `~/.ssh/id_rsa`, keychain extraction, hardcoded API keys)
- Remote code execution (`curl ... | bash`, `eval`, `base64 -d | sh`)
- Hook, LaunchAgent, or cron installation attempts
- Reverse shells (`nc -e`, `/dev/tcp/...`)
- Caution-level: external network fetches to non-allowlisted domains, file overwrites, system-prompt dump requests, recursive skill chaining

**Semantic scan (Cerebras free tier, about a second):**
- Asks a cheap model to flag the same five concerns in natural language, catching paraphrased patterns the regex misses. Needs a free `CEREBRAS_API_KEY` (see Setup below); the pattern scans above work with zero setup, and the audit still runs without it.

**Author reputation:**
- A short starting list of known-good publishers lowers the bar. Edit `KNOWN_GOOD_AUTHORS` in `audit.py` to add your own trusted authors.
- Unknown authors default to CAUTION even with zero pattern hits.

## Setup (optional, for the semantic pass)

```bash
export CEREBRAS_API_KEY=...   # free at cloud.cerebras.ai → API Keys
```

No key and no extra package are required for the pattern-scan half of the audit. Only the semantic second pass needs a key, and it fails open, meaning it skips rather than blocks, if the key is missing.

## Protocol for callers

Any skill or agent that installs other skills on your behalf should follow this:

1. **Before any `npx skills add` (or equivalent install) call**, run:
   ```bash
   python3 audit.py "<spec>"
   ```
2. Show the rendered report verbatim to whoever approves the install.
3. Branch on verdict:
   - **SAFE** → proceed with install. State the verdict.
   - **CAUTION** → STOP. Surface the findings. Get an explicit approve-or-skip.
   - **UNSAFE** → STOP. Surface the report. Recommend skip. Do not proceed even on a vague “go ahead.”
   - **UNKNOWN** → STOP. The source could not be fetched. Try a direct URL or skip.
4. **Never** install on a CAUTION/UNSAFE/UNKNOWN verdict based on inferred consent. The verdict has to be visible to whoever approves, every time.

## Updating the known-good author list

Edit `KNOWN_GOOD_AUTHORS` in `audit.py`. Add author handles only after you’ve personally reviewed their work, or after several of their skills have come back SAFE on both the pattern and semantic passes.

## When to call this directly

- Someone says “audit this skill” / “is X safe to install” / “/ww-skill-auditor X”
- Someone shares a GitHub URL pointing to a SKILL.md and asks about it
- You’re an automated agent proposing to install a skill on your own

## Limitations

- Audits the SKILL.md content by default. Skills that ship auxiliary scripts still need their own code review. A clean SKILL.md doesn’t guarantee a clean script sitting next to it.
- The regex set is a starting point. Extend `UNSAFE_PATTERNS` / `CAUTION_PATTERNS` as new attack shapes turn up; each new pattern is a lesson encoded for the next install.
- The semantic check uses Cerebras’s free tier. If it’s down or unconfigured, the audit continues without it, still useful, just less thorough.
- Author reputation is one signal, not a guarantee. A known-good author can still ship a regressed skill, so pattern hits always override the reputation pass.