ondrej-merkun skill-audit
Use the published CLI unless the user explicitly asks to test a local checkout:
npx --yes @ondrej-merkun/skill-audit@latest
The bare command is the default scan and is equivalent to skill-audit scan.
It scans installed or currently exposed skill surfaces by default, keeps all
rule scanning local, and does not execute skill code.
Recommended Workflow
For a normal audit, run the human-readable scan first:
npx --yes @ondrej-merkun/skill-audit@latest scan
Then summarize:
- Total skills scanned, compromised count, and overall verdict.
- FAIL-verdict skills first, with the top issue and one-line remediation.
- REVIEW-verdict skills that need human judgment.
- Suggested follow-up commands, usually
explain,ignore, or a JSON/HTML report.
Always show the skill-audit table or summary output verbatim in a code block
before interpreting it. For automation or CI-style requests, use --json and
summarize the parsed JSON instead.
Do not recommend rm, delete, uninstall, or file-editing commands without
explicit user confirmation. Prefer skill-audit explain <skill> first, and
use skill-audit ignore <skill> only after the user has reviewed the exact
installed tree and wants to suppress a false positive.
Commands
Global options:
| Option | Use |
|---|---|
-V, --version |
Print the installed CLI version. |
-h, --help |
Print command help. |
Default Scan
npx --yes @ondrej-merkun/skill-audit@latest
npx --yes @ondrej-merkun/skill-audit@latest scan
Scans discovered skills with deterministic local rules and prints the table
output. Exit codes: 0 PASS, 1 threshold failure, 2 usage/runtime error,
3 incomplete scan without a threshold failure.
scan
npx --yes @ondrej-merkun/skill-audit@latest scan [options]
Options:
| Option | Use |
|---|---|
--json |
Emit schema v1.0 JSON to stdout. |
--summary |
Emit compact one-line summary output. |
--html <file> |
Write a standalone HTML report and still print the selected scan payload. |
-o, --output <file> |
Write the selected non-HTML output to a file instead of stdout. |
--strict |
Treat REVIEW as FAIL for exit-code purposes. |
--fail-on <band> |
Set exit threshold to FAIL or REVIEW; default is FAIL. |
--agent <id> |
Restrict scan to one agent id. |
--skill <name-or-id> |
Restrict scan to one matching skill. |
--include-marketplaces |
Include inactive local marketplace inventory as well as installed/exposed skills. |
--llm <name> |
Add optional local LLM review; repeat, comma-separate, or pass all. |
--offline |
Hidden maintenance option; skip enrichment and LLM review. Use only when explicitly requested. |
Supported --agent ids are claude-code, codex, cross-agent, cursor,
gemini, copilot, windsurf, and cline.
Output combinations:
npx --yes @ondrej-merkun/skill-audit@latest scan --json
npx --yes @ondrej-merkun/skill-audit@latest scan --summary
npx --yes @ondrej-merkun/skill-audit@latest scan --json --output skill-audit-results.json
npx --yes @ondrej-merkun/skill-audit@latest scan --summary --output skill-audit-summary.txt
npx --yes @ondrej-merkun/skill-audit@latest scan --output skill-audit-report.txt
npx --yes @ondrej-merkun/skill-audit@latest scan --html skill-audit-report.html
Do not combine --html and --output; that is a usage error.
Scope examples:
npx --yes @ondrej-merkun/skill-audit@latest scan --agent claude-code
npx --yes @ondrej-merkun/skill-audit@latest scan --agent codex --json
npx --yes @ondrej-merkun/skill-audit@latest scan --skill obfuscated-eval-skill
npx --yes @ondrej-merkun/skill-audit@latest scan --include-marketplaces
npx --yes @ondrej-merkun/skill-audit@latest scan --json --fail-on REVIEW
npx --yes @ondrej-merkun/skill-audit@latest scan --strict
Local LLM review examples:
npx --yes @ondrej-merkun/skill-audit@latest scan --llm local
npx --yes @ondrej-merkun/skill-audit@latest scan --skill obfuscated-eval-skill --llm local
npx --yes @ondrej-merkun/skill-audit@latest scan --llm local --llm qwen
npx --yes @ondrej-merkun/skill-audit@latest scan --llm local,qwen --summary
npx --yes @ondrej-merkun/skill-audit@latest scan --llm all --html skill-audit-report.html
LLM review is a second opinion. It does not replace deterministic findings or change the deterministic rule results. Model failures, timeouts, and invalid responses must be reported as LLM review status, not treated as scanner PASS.
list
npx --yes @ondrej-merkun/skill-audit@latest list [options]
Lists discovered skills without scanning their contents.
Options:
| Option | Use |
|---|---|
--agent <id> |
Restrict inventory to one agent id. |
--include-marketplaces |
Include inactive marketplace inventory and label install state. |
--json |
Emit a JSON array with agent, name, path, tree hash, scope, install state, and format. |
Examples:
npx --yes @ondrej-merkun/skill-audit@latest list
npx --yes @ondrej-merkun/skill-audit@latest list --agent codex
npx --yes @ondrej-merkun/skill-audit@latest list --include-marketplaces
npx --yes @ondrej-merkun/skill-audit@latest list --json
explain
npx --yes @ondrej-merkun/skill-audit@latest explain <skill-name-or-id> [options]
Shows the full detail view for one skill, including findings and remediation. Use this before suggesting any destructive cleanup.
Options:
| Option | Use |
|---|---|
--json |
Emit the detail payload as JSON. |
--llm <name> |
Add optional local LLM review for this selected skill. |
--offline |
Hidden maintenance option; skip disabled network enrichment. |
Examples:
npx --yes @ondrej-merkun/skill-audit@latest explain obfuscated-eval-skill
npx --yes @ondrej-merkun/skill-audit@latest explain obfuscated-eval-skill --llm local
npx --yes @ondrej-merkun/skill-audit@latest explain obfuscated-eval-skill --json
ignore
npx --yes @ondrej-merkun/skill-audit@latest ignore <skill-name-or-id>
Adds the selected skill's current treeSha256 to the local ignore list so
subsequent scans skip it. Use only for a reviewed false positive. A changed
skill tree gets a different hash and must be reviewed again.
llm add
npx --yes @ondrej-merkun/skill-audit@latest llm add <name> --base-url <url> --model <id> [options]
Stores a named local OpenAI-compatible review model. The base URL must be a
loopback HTTP(S) URL such as http://127.0.0.1:11434/v1 or
http://localhost:1234/v1; credentials in URLs and non-loopback hosts are
rejected.
Required options:
| Option | Use |
|---|---|
--base-url <url> |
Local OpenAI-compatible server base URL. |
--model <id> |
Local model id to send to /v1/chat/completions. |
Optional options:
| Option | Use |
|---|---|
--provider <provider> |
Provider type; only openai-compatible is supported. |
--timeout <ms> |
Positive integer health-check timeout in milliseconds. |
--context-tokens <tokens> |
Positive integer token budget for LLM review payloads. |
--disabled |
Store the model but exclude it from --llm all and scan review. |
Example:
npx --yes @ondrej-merkun/skill-audit@latest llm add local --base-url http://127.0.0.1:11434/v1 --model llama3.1
Configs are written to $XDG_CONFIG_HOME/skill-audit/llms.json, or
~/.config/skill-audit/llms.json when XDG_CONFIG_HOME is unset.
llm list
npx --yes @ondrej-merkun/skill-audit@latest llm list [--json]
Lists configured local review models and whether each is enabled.
llm check
npx --yes @ondrej-merkun/skill-audit@latest llm check <name> [--json]
Health-checks one configured model by sending a minimal local
OpenAI-compatible chat-completions request. Status values are ok,
unavailable, timeout, or invalid-response.
Discovery Surface
Default scan and list include installed or currently exposed skills and
project instruction files. Marketplace cache payloads are inactive inventory
unless --include-marketplaces is set.
Current built-in discovery covers:
- Claude Code skills, commands, agents, plugins, MCP config, and project files.
- Codex global/project instructions, skills, prompts, plugins, and config.
- Cursor, GitHub Copilot, and Gemini skill/instruction surfaces.
- Cross-agent project instruction files such as
AGENTS.md.
Reporting Guidance
When presenting results:
- Keep deterministic rule findings authoritative.
- State when LLM review was requested and whether each model returned
ok,unavailable,timeout, orinvalid-response. - Treat PASS as "no shipped rule matched", not proof of safety.
- For FAIL findings, recommend reviewing the detail view and removing the risky
instruction/code, then rerunning
scanorexplain. - For REVIEW findings, explain what human judgment is needed.
- For false positives, ask whether the user wants to run
ignore; do not suppress automatically.