SkillSpector: Security Scanner for AI Agent Skills

What SkillSpector is

SkillSpector is a security scanner for AI agent skills, published by NVIDIA under the Apache-2.0 license. Agent skills are the packaged instructions, scripts, and dependencies that coding agents such as Claude Code, Codex CLI, and Gemini CLI load to extend what they can do. The README points out that these skills execute with implicit trust and minimal vetting, and cites research to make the point: in a 31,132-skill analyzed subset of a dataset from the paper "Agent Skills in the Wild: An Empirical Study of Security Vulnerabilities at Scale" (Liu et al., 2026), 26.1% of skills contained at least one vulnerability and 5.2% showed likely malicious intent. The same research reports that skills with executable scripts are 2.12 times more likely to be vulnerable.

The question SkillSpector is built to answer is short: is this skill safe to install? It takes a skill from a Git repository, URL, zip file, directory, or single SKILL.md file, analyzes it, and returns a 0-100 risk score with a severity label and a recommendation. It is also part of NVIDIA's Verified Skills pipeline, which scans, evaluates, and signs skills before they are published to the NVIDIA skills catalog.

It is aimed at developers who install third-party skills, platform teams who want to gate skill installation in CI or inside agent sessions, and anyone running a skill marketplace.

How it works

SkillSpector uses a two-stage detection pipeline, orchestrated as a LangGraph workflow.

Stage 1: static analysis

The first stage runs regex-based pattern matching across 11 static analyzers, AST-based behavioral analysis that looks for dangerous calls such as exec, eval, and subprocess, taint tracking from sources to sinks, YARA signature matching, and live vulnerability lookups against OSV.dev for declared dependencies. The README describes this stage as high recall with moderate precision, meaning it catches most issues but produces some false positives.

Stage 2: LLM semantic analysis (optional)

The second stage sends file contents to a configured LLM to evaluate context and intent, filter false positives, and write human-readable explanations. The README claims this improves precision to around 87%, and says the prompt includes anti-jailbreak protections so a malicious skill cannot talk the analyzer out of flagging it. Pass --no-llm to skip this stage.

Risk scoring

Each finding adds to the score: 50 points for critical, 25 for high, 10 for medium, and 5 for low, with a 1.3x multiplier when the skill contains executable scripts. Scores of 0-20 map to LOW and SAFE, 21-50 to MEDIUM and CAUTION, and anything above 50 to HIGH or CRITICAL with a DO NOT INSTALL recommendation.

Key features

• 71 vulnerability patterns in 17 categories: 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.
• Agent-specific checks: patterns such as overly broad triggers, triggers that shadow built-in commands, instructions to never refuse, and hidden directives in MCP tool metadata using zero-width characters or homoglyphs.
• Supply chain checks: unpinned and abandoned dependencies, typosquatting, curl | bash style fetching, shipped Python bytecode, and dependency source redirection.
• Multiple output formats: terminal, JSON, Markdown, and SARIF 2.1.0 for CI and IDE tooling.
• Baselines: accept known findings via glob rules or exact fingerprints so later scans report only new issues.
• Many LLM providers: OpenAI, Anthropic, AWS Bedrock, Azure OpenAI, NVIDIA build.nvidia.com, Ollama, any OpenAI-compatible endpoint, and local Claude, Codex, Gemini, or OpenCode CLIs that reuse their own login sessions.
• MCP server mode: exposes a single scan_skill tool so an agent can check a skill and gate its own installs on the result.
• Stable integration contract: documented exit codes and JSON shape, plus a Python API.
• Fail-closed ingest limits: a 100 MiB per-ingest cap and a 10,000-member zip cap guard against oversized downloads and zip bombs.

Getting started

The quickest path is a CLI-only install with uv:

uv tool install git+https://github.com/NVIDIA/skillspector.git
# Update later: uv tool update skillspector

If you want MCP server mode, install the extra:

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

Basic scans:

# Scan a local skill directory
skillspector scan ./my-skill/

# Scan a single SKILL.md file
skillspector scan ./SKILL.md

# Scan a Git repository
skillspector scan https://github.com/user/my-skill

# Scan a zip file
skillspector scan ./my-skill.zip

For CI, emit SARIF, and to keep scans fully local, skip the LLM stage:

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

A Dockerfile based on python:3.12-slim-bookworm is included if you would rather not install Python:

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

To register it as an MCP tool in Claude Code:

claude mcp add skillspector -- skillspector mcp

Use cases

• Vetting a skill before install: run a scan on a skill's Git URL before adding it to your agent and read the explanations for any HIGH findings.
• CI gating for a skills repository: use exit codes (0 for score 50 or below, 1 for above 50 or a strict gate firing, 2 for errors) with --fail-on-findings or --fail-on-incomplete for stricter policies, and upload SARIF to code scanning.
• Runtime guardrail inside an agent: run skillspector mcp so the agent itself calls scan_skill and refuses installs that come back safe_to_install: false.
• Marketplace or catalog review: the batch scanner in contrib/batch_scan/ scans whole directories of skills in parallel and supports zh, ja, and ko detection.
• Tracking regressions: commit a baseline file and only new findings affect the score on later scans.

How it compares

The README does not compare SkillSpector against named alternatives. In practical terms it sits between general static analysis tools and secret scanners on one side and agent runtime sandboxes on the other. Its distinguishing scope is that it understands agent-specific attack surfaces, such as prompt injection inside SKILL.md, trigger abuse, and MCP tool poisoning, alongside conventional code and dependency checks. It is a pre-install check rather than an isolation layer, so it complements rather than replaces sandboxing.

Things to know before adopting

• Data egress: LLM analysis is on by default and sends analyzer-eligible file contents to the configured provider. The default provider is nv_build. Use --no-llm to keep content local.
• OSV.dev lookups always run: the SC4 dependency check sends package names and versions to OSV.dev even with --no-llm, falling back to a small bundled list when offline.
• Not a sandbox: SkillSpector never executes the skill, and it does not contain a skill you decide to install anyway.
• Stated limitations: it may miss patterns in non-English content, cannot read text inside images, cannot analyze compiled or encrypted code, and does not observe runtime behavior.
• HTTP MCP transport has no authentication: put it behind an authenticating reverse proxy before exposing it. Local paths and file:// URLs are rejected over HTTP.
• Version pinning quirks: the opencode_cli provider fails closed unless OpenCode 1.18.32 is installed, and the README notes a known initialize hang on the stdio MCP transport.
• Python 3.12+ is required for non-Docker installs.

Project activity

As of October 2026 the repository has roughly 19,000 stars. It was created on March 21, 2026, is written in Python, and is licensed under Apache-2.0. Source code is at github.com/NVIDIA/SkillSpector, and the hosted guide to scanning skills before installation is at docs.nvidia.com/skills/scanning-agent-skills. The repository also includes a development guide, suppression documentation, and extensions for running SkillSpector from inside Pi and OpenCode sessions.