SkillSpector: A Security Scanner That Checks AI Agent Skills Before You Install Them

The Problem: Skills Run With Implicit Trust

AI agent skills are small packages of instructions and code that agents like Claude Code, Codex CLI, and Gemini CLI execute with little vetting. The README cites research that 26.1% of skills contain vulnerabilities and 5.2% show likely malicious intent. That is the problem SkillSpector addresses: it gives you a way to ask whether a skill is safe to install before you run it. The tool is aimed at developers and platform teams who pull skills from public repositories or marketplaces and need a repeatable check. It is also part of NVIDIA's Verified Skills pipeline, which scans, evaluates, and signs skills before publication. That context matters: this is not a generic security scanner, it is a specialized tool for a specific attack surface that has grown with the adoption of agent-based workflows.

Two-Stage Analysis: Static Patterns Plus Optional LLM Review

SkillSpector works in two stages. The first stage is fast static analysis. It applies 71 vulnerability patterns across 17 categories, including prompt injection, data exfiltration, privilege escalation, supply chain, excessive agency, output handling, system prompt leakage, memory poisoning, tool misuse, rogue agent, anti-refusal, trigger abuse, dangerous code via AST, taint tracking, YARA signatures, MCP least privilege, and MCP tool poisoning. That is a wide net. The second stage is optional LLM semantic evaluation. You can run a scan with or without an LLM, controlled by a flag like --no-llm. The static stage is deterministic and fast; the LLM stage adds context that pattern matching cannot capture. The design is sensible: get quick, reproducible results first, then decide if you need deeper analysis.

Input Flexibility and Resource Limits

You can scan a local directory, a single SKILL.md file, a Git repository URL, a zip file, or a single file. That covers the common ways skills are distributed. To bound the risk of oversized downloads and zip bombs, the tool enforces two independent caps. INGEST_MAX_BYTES defaults to 100 MiB and applies to streamed URL downloads, total uncompressed size of zip archives, and post-clone disk usage of Git repos. INGEST_MAX_ZIP_MEMBERS caps zip entries at 10,000. A separate downstream limit, MAX_FILE_BYTES, caps individual file analysis at 1 MB. A breach of either ingest cap fails closed with an IngestLimitExceededError. This is a thoughtful design: it prevents a malicious skill from exhausting disk or memory before analysis even runs. The trade-off is that very large skills, or skills with many small files, may be refused outright even if they are legitimate.

Getting It Running: Commands and Config

Installation is straightforward with uv or pip. The quickest path is uv tool install git+https://github.com/NVIDIA/skillspector.git. If you need the MCP extra, install skillspector[mcp] at the same time. From source, clone the repo, create a virtual environment, and run make install or make install-dev. Docker is also supported: build the image with make docker-build, then run a scan by mounting your current directory into /scan. For example: docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm. To use LLM analysis, you set environment variables like SKILLSPECTOR_PROVIDER and ANTHROPIC_API_KEY, either via a .env file or directly. Output formats include terminal, JSON, Markdown, and SARIF. SARIF is the key one for CI/CD integration, since it is a standard format that IDEs and pipelines can consume.

Suppression and Baselines: Handling False Positives

Security scanners produce false positives, and SkillSpector has a mechanism to deal with them. The README mentions a baseline and false-positive suppression feature: you can accept known findings via a glob-rule or fingerprint baseline, so re-scans surface only new issues. This is documented in docs/SUPPRESSION.md. The approach is practical: you run a scan on a trusted skill, record the findings, and then future scans ignore those specific patterns. The risk is that a baseline can hide real issues if you suppress too broadly. The fingerprint option is safer than glob rules because it targets exact findings, but it requires maintenance as skills evolve. This feature is essential for any real deployment, because without it, the scanner would be noisy on every scan and teams would stop using it.

Limitations and Failure Modes

The most obvious limitation is that SkillSpector is pattern-based. It detects known vulnerability patterns, but it cannot prove a skill is safe. A novel attack that does not match any of the 71 patterns will pass. The README itself frames the tool as helping you answer 'Is this skill safe to install?' but the honest answer is that it reduces risk, it does not eliminate it. Second, the LLM stage is optional and needs a configured LLM provider, which adds a dependency. If you run with --no-llm, you lose the semantic analysis that might catch context-dependent issues. Third, the resource limits can be a wrong-tool case: if you need to scan a remote or archived skill that exceeds 100 MiB, the scanner will fail closed. That is safe but frustrating. Finally, the tool is designed for agent skills specifically, so scanning a general-purpose codebase will produce noise or miss relevant issues. It is the wrong tool for general code security review.

Alternatives and How They Differ

The closest alternative is the ecosystem of general-purpose static analysis tools, such as Semgrep or Bandit for Python. Semgrep uses custom rules and can be adapted to scan skill files, but it does not have the 17 predefined categories for agent-specific threats like prompt injection or MCP tool poisoning. Bandit is Python-focused and would miss the SKILL.md instruction content. Another alternative is the NVIDIA Verified Skills pipeline itself, which includes SkillSpector as a component but adds evaluation and signing. The difference is that Verified Skills is NVIDIA's pipeline for skills published to the NVIDIA skills catalog, while SkillSpector is a standalone scanner you run yourself. If you need to integrate scanning into your own CI without sending code to a third party, SkillSpector gives you local control. Skills published to the NVIDIA skills catalog have already passed that pipeline.

Maintenance, Licensing, and Upgrade Cost

SkillSpector is Apache-2.0 licensed, which means you can use, modify, and distribute it freely, including in commercial products, as long as you preserve the license notice. The repository is actively maintained, with recent releases v2.13.1, v2.13.2 and v2.13.3 between 2026-10-23 and 2026-11-02, suggesting a steady release cadence. Upgrade cost is moderate: installing via uv tool update skillspector is simple, but you should re-run baseline scans after each update because new patterns may trigger new findings on previously suppressed issues. The README also warns that the project downloads and installs additional third-party open source software, so you need to review those license terms before use. That is a real consideration for teams with strict license compliance requirements.

Editorial conclusion

Adopt SkillSpector if you regularly install skills from untrusted sources into Claude Code, Codex CLI, Gemini CLI, or similar agents and need a first-line vetting tool that runs locally or in CI. Skip it if your skills are all internal and reviewed manually, or if you cannot accept the risk of false negatives from a pattern-based scanner that does not guarantee safety. Before relying on it, verify the 71 patterns cover the skill types you use, test the baseline suppression with your own known-good skills, and check the resource limits (INGEST_MAX_BYTES, INGEST_MAX_ZIP_MEMBERS, MAX_FILE_BYTES) against your typical inputs. The scanner is a useful gate, not a proof of safety, and its effectiveness depends on keeping the rule set updated.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes