Part of Claude Code 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
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)
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:
- Before any
npx skills add (or equivalent install) call, run:python3 audit.py "<spec>"
- Show the rendered report verbatim to whoever approves the install.
- 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.
- 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.
1---2name: ww-skill-auditor3description: 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.4---56> 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.78# Skill auditor: a security gate before you install any third-party skill910A 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.1112## Mandate1314**Anything that introduces external instructions into your agent’s context should pass this audit before install.** That includes:1516- `npx skills add` invocations17- Cloning a skills/agents/plugins repo into `~/.agents/skills/`, `~/.claude/skills/`, or any project-local skills folder18- Adding a hook to `~/.claude/settings.json` or a project’s `.claude/settings.json`19- Installing a scheduled job (LaunchAgent, cron, systemd timer) that was authored externally20- Reading a SKILL.md from a URL someone points you at and being asked to follow it2122Severity 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.2324## How to run it2526### From a terminal or a Bash tool call2728```bash29python3 audit.py "<author>/<repo>/<skill>"30```3132Run it from this skill’s own directory, or pass the full path to `audit.py`.3334Accepted input forms:35- `npx skills add` spec: `someauthor/somerepo/some-skill`36- Raw GitHub URL: `https://raw.githubusercontent.com/.../SKILL.md`37- GitHub blob/tree URL: `https://github.com/.../tree/main/skill-name`38- Local file: `--file /path/to/SKILL.md`3940Add `--json` for machine-readable output.4142### Exit codes4344| Code | Verdict | Meaning |45|-----:|---------|---------|46| 0 | SAFE | No signals. Known-good author. Proceed. |47| 1 | CAUTION | Low-risk findings, or an unknown author. Review before you approve. |48| 2 | UNSAFE | High-risk pattern hit. **Do NOT install.** |49| 3 | UNKNOWN | Could not fetch, or inconclusive. Do not install until the source is locatable. |5051## What it checks5253**Deterministic regex scans (fast, no API):**54- Prompt-injection overrides (“ignore previous instructions,” jailbreaks)55- Credential exfiltration (`.env`, `~/.ssh/id_rsa`, keychain extraction, hardcoded API keys)56- Remote code execution (`curl ... | bash`, `eval`, `base64 -d | sh`)57- Hook, LaunchAgent, or cron installation attempts58- Reverse shells (`nc -e`, `/dev/tcp/...`)59- Caution-level: external network fetches to non-allowlisted domains, file overwrites, system-prompt dump requests, recursive skill chaining6061**Semantic scan (Cerebras free tier, about a second):**62- 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.6364**Author reputation:**65- A short starting list of known-good publishers lowers the bar. Edit `KNOWN_GOOD_AUTHORS` in `audit.py` to add your own trusted authors.66- Unknown authors default to CAUTION even with zero pattern hits.6768## Setup (optional, for the semantic pass)6970```bash71export CEREBRAS_API_KEY=... # free at cloud.cerebras.ai → API Keys72```7374No 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.7576## Protocol for callers7778Any skill or agent that installs other skills on your behalf should follow this:79801. **Before any `npx skills add` (or equivalent install) call**, run:81 ```bash82 python3 audit.py "<spec>"83 ```842. Show the rendered report verbatim to whoever approves the install.853. Branch on verdict:86 - **SAFE** → proceed with install. State the verdict.87 - **CAUTION** → STOP. Surface the findings. Get an explicit approve-or-skip.88 - **UNSAFE** → STOP. Surface the report. Recommend skip. Do not proceed even on a vague “go ahead.”89 - **UNKNOWN** → STOP. The source could not be fetched. Try a direct URL or skip.904. **Never** install on a CAUTION/UNSAFE/UNKNOWN verdict based on inferred consent. The verdict has to be visible to whoever approves, every time.9192## Updating the known-good author list9394Edit `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.9596## When to call this directly9798- Someone says “audit this skill” / “is X safe to install” / “/ww-skill-auditor X”99- Someone shares a GitHub URL pointing to a SKILL.md and asks about it100- You’re an automated agent proposing to install a skill on your own101102## Limitations103104- 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.105- 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.106- The semantic check uses Cerebras’s free tier. If it’s down or unconfigured, the audit continues without it, still useful, just less thorough.107- 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.
lee-fuhr