SkillSpector

What it is

SkillSpector is a CLI security scanner for AI agent skills (Claude Code, Codex CLI, Gemini CLI). The summary covers its detection scope; this document carries the operational details it omits — how to install it, run it in CI, and the resource limits that bound its behavior on hostile inputs.

How it works

Two-stage: fast static analysis runs by default; LLM semantic evaluation is opt-in and requires a provider key. It accepts Git repos, URLs, zip files, directories, or single files. Baseline suppression lets you accept known findings via glob-rule or fingerprint so re-scans surface only new issues. A contrib/batch_scan module scans directories of skills in parallel (--workers 20), with multilingual detection (zh/ja/ko).

Ingest is bounded by two independent caps to resist oversized downloads and zip bombs: INGEST_MAX_BYTES (100 MiB, applied to URL downloads, total uncompressed zip size, and post-clone repo disk usage) and INGEST_MAX_ZIP_MEMBERS (10,000 entries). A separate downstream MAX_FILE_BYTES (1 MB) caps what individual analyzers read per file. Breaching either ingest cap fails closed with IngestLimitExceededError — worth knowing if a legitimate large skill is silently rejected.

What to do

Install CLI-only via uv:

uv tool install git+https://github.com/NVIDIA/skillspector.git

For the in-session MCP tool (skillspector mcp), install the extra:

uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

Basic scans:

skillspector scan ./my-skill/
skillspector scan https://github.com/user/my-skill
skillspector scan ./my-skill.zip

For CI/CD, emit SARIF (consumed by IDEs and code-scanning dashboards):

skillspector scan ./my-skill/ --format sarif --output report.sarif

Docker without a local Python, mounting the working dir into /scan:

docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm

Pass --no-llm to force static-only (no key, no network to a provider). LLM scans need SKILLSPECTOR_PROVIDER and the provider key (e.g. ANTHROPIC_API_KEY) via --env-file .env or -e.

Caveats

• Install downloads and installs additional third-party open-source projects — review their licenses before use.
• LLM semantic evaluation is optional and off by default; static-only scans forgo that layer.
• Live CVE lookups query OSV.dev with automatic offline fallback, so results can differ between online and offline runs.