How to Use NVIDIA SkillSpector: The Beginner's Guide (Scan Your Agent Skills Before You Install Them)

CodexFuse Team · 2026-11-03T06:23:07.780Z · 11 min read min read

What Is NVIDIA SkillSpector, Exactly?

NVIDIA SkillSpector is an open-source AI agent skill security scanner that answers one question before you install anything: is this skill safe to install? It is free, runs locally, and needs no account for its core static scan. This guide covers how to use SkillSpector end to end: install, your first scan, the 0–100 score, and the one privacy rule you must not skip.

SkillSpector runs fast, deterministic static checks by default, and can add an optional LLM-powered semantic pass for issues that require comparing what a skill claims with what its code appears to do, according to the current NVIDIA Skill Documentation page (docs.nvidia.com/skills/scanning-agent-skills), which I read while writing this guide. It accepts Git repositories, URLs, zip files, directories, and single files — whatever form the skill arrives in.

If you run an always-on coding agent, this is the missing gate for your setup: skills like the ones installed for the agent in our OpenClaw beginner guide arrive as a single markdown file plus whatever scripts ship beside it, and they run with your agent's permissions the moment you install them.

Why Do Skills Need a Security Scan Before Install?

Because a skill installs in one command and then runs with your agent's full access — your files, your terminal, your API keys — and nothing in the normal install path checks what it actually does.

Here is the scenario the scanner was built for. You install a skill called pdf-formatter because your agent needs to clean up some documents. It works. What you do not see is the scripts/sync.py bundled alongside the SKILL.md — the one that iterates over os.environ and posts the results to an external endpoint. That example comes from an independent review of SkillSpector by Rushi (rushis.com), and it is the classic pattern: the description says one thing, the bundled code does another.

The problem is not theoretical. NVIDIA's own research on a 31,132-skill subset found that 26.1 percent of the skills carried flaws — reported in the digisoulhub.com review of the project. Treat that figure exactly as what it is: NVIDIA's measurement on their own dataset, not a universal law — but it tells you why a scan-before-install habit is worth the sixty seconds it costs. When you scan agent skills for malware, prompt injection, and data exfiltration in one pass, you are closing the one hole the normal install path leaves wide open.

How Do You Install SkillSpector?

The fastest path is one uv command that installs the scanner straight from NVIDIA's repository — no account, no API key needed for the static scan.

1. Install uv if you do not have it yet (the official docs assume either uv or plain Python 3).
2. Install SkillSpector: uv tool install git+https://github.com/NVIDIA/skillspector.git. This one-liner is reported working by the digisoulhub.com and opusjake.ai write-ups. Later, update it with uv tool update skillspector.
3. Or install from source per the official docs: clone the repository, create a virtual environment, and run make install:

   git clone https://github.com/NVIDIA/SkillSpector.git
   cd SkillSpector
   uv venv .venv && source .venv/bin/activate
   make install

   If uv is unavailable, the docs give the plain-Python equivalent: python3 -m venv .venv, then activate and make install.
4. Or run it in Docker if you would rather not install Python at all: build the image that ships in the repo and mount the folder you want scanned (the opusjake.ai guide documents this path):

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

Whichever path you take, run your first scan next — that is your install confirmation.

Your First Scan in Five Steps

Start with what you already trust, then make the pre-install scan a habit:

1. Pick a trusted target. Everything in ~/.claude/skills/ went in without a check, so scan that folder first — it is the fastest way to learn the tool on real files.
2. Run the scan: skillspector scan ~/.claude/skills/ --no-llm. The --no-llm flag keeps this first pass static-only: fast, offline, and no API key.
3. Read the report header. A real sample report (version 0.1.0, shown in Rushi's review) looks like this: Skill: suspicious-skill — Score: 78/100 — Severity: HIGH — Recommendation: DO NOT INSTALL. One number, one severity, one instruction.
4. Open the findings and ask one question: does each flagged item match what the skill claims to do? A flagged network call inside a skill that claims to work offline is the classic tell.
5. Lock in the habit: scan the next skill repo before you clone it, not after. The repo URL is a valid scan target, so the check costs nothing extra.

What the 0–100 Risk Score Tells You

The SkillSpector risk score is the verdict, not a debate starter: one number, one severity, one plain-English instruction.

These bands come from SkillSpector's own scoring as documented by the stevetan.com install-gate guide. Two rules worth pinning above your desk: read the recommendation before installing anything, and never treat a completed scan as an approval.

What SkillSpector Checks Under the Hood

The current official docs page lists 68 vulnerability patterns across 17 categories — and the count grows with each release, so treat any exact figure as version-bound (the digisoulhub.com review, checking the README on October 27, 2026, reported 71 patterns; that is how fast this project moves).

The categories the docs name include prompt injection, data exfiltration, privilege escalation, supply-chain issues, excessive agency, output handling, system prompt leakage, memory poisoning, tool misuse, rogue-agent behavior, trigger abuse, dangerous code patterns, taint tracking, YARA signatures, MCP least privilege, and MCP tool poisoning.

Beyond pattern matching, the scanner supports live vulnerability lookup through OSV.dev for known vulnerable dependencies, with an offline fallback when network access is unavailable, per the official docs.

And if you are preparing a skill for publication rather than reviewing one for install, note the relationship: SkillSpector is also the security tier (Tier 1) inside NVIDIA's SkillEvaluator — scanning determines whether a skill is safe to ship, while evaluation determines whether it improves an agent's output. This guide covers running the scanner directly, the pre-install use case.

The LLM Pass and the Privacy Rule You Must Not Skip

Say this rule loudly, once, and never forget it: turning on the semantic LLM pass sends the skill's contents to the model provider you configure — so never scan a skill containing secrets or private code against an external provider.

Static analysis is fast and deterministic. It catches suspicious strings, dependency risk, dangerous APIs, and declared-permission mismatches, per the official docs. The semantic pass uses an LLM to compare what a skill claims with what its code appears to do — which is what catches description-behavior mismatches, vague triggers, and subtle policy issues that static rules miss.

The default provider is NVIDIA's build.nvidia.com inference service, with OpenAI and Anthropic also built in, and local servers like Ollama, vLLM, or llama.cpp supported via OPENAI_BASE_URL (documented in Rushi's review). Configure it per the official docs:

export SKILLSPECTOR_PROVIDER=openai
export OPENAI_API_KEY=your-key-here
skillspector scan ./my-skill/

The private way to get semantic checks without sending skill contents anywhere is the local option: point the scanner at a model on your own machine, exactly what our Ollama beginner guide sets up.

To skip the LLM entirely — fast, offline, deterministic — add --no-llm, per the official docs. One caveat even there: with --no-llm, the scanner still sends declared dependency names and versions to OSV.dev for vulnerability checks when that service is reachable (the stevetan.com guide flags this). So "offline" means your skill's contents stay on your machine — dependency metadata goes out if the network is up. For truly private code, scan with no network at all; the offline fallback exists.

Folder, File, Repo, or Zip: The Four Scan Targets

SkillSpector meets the skill wherever it is — you never have to install or unpack anything before the check:

All four forms come straight from the official docs page. Two practical limits to know, reported by the digisoulhub.com review: downloads are capped at 100 MiB and zip archives at 10,000 entries. The scanner covers skills for Claude Code, Codex CLI, Gemini CLI, and MCP — so as a Claude Code skill scanner and everything else, one tool guards every agent on your machine.

Terminal, JSON, Markdown, or SARIF: Choosing an Output Format

Match the format to the job: use terminal output while iterating locally, JSON for automation, Markdown for review packets, and SARIF for CI or code-scanning systems, per the official docs.

# Pretty terminal output while iterating
skillspector scan ./my-skill/

# Machine-readable JSON for automation
skillspector scan ./my-skill/ --format json --output report.json

# Human-readable report for a review packet
skillspector scan ./my-skill/ --format markdown --output report.md

# CI and IDE integration
skillspector scan ./my-skill/ --format sarif --output report.sarif

The SARIF branch is the CI gate: the report drops straight into GitHub code-scanning and IDE tooling, which is how a team turns "scan before install" from a suggestion into an enforced step.

How Do You Let Your Agent Scan Its Own Skills?

Register SkillSpector as an MCP server and the gate stops being a thing you remember to run — it becomes a thing that happens on its own, because the agent checks itself before every install.

1. Register the server (documented in the opusjake.ai guide): claude mcp add skillspector -- skillspector mcp
2. Tell your agent once: "Before installing any skill or MCP server, scan it with skillspector first. If the recommendation is DO_NOT_INSTALL, stop and show me the findings."
3. Let the verdict drive the decision. The server exposes a single tool, scan_skill, and hands back a verdict the agent can act on: risk_score, severity, recommendation, safe_to_install, and the findings.

This is not Claude-Code-only: the docs include extensions for Pi and OpenCode, per the digisoulhub.com review, so the self-scanning agent works inside other agent sessions too. If the MCP part is new to you, our Claude Code beginner guide covers the agent this scanner was designed to protect.

Where a Clean Score Stops Short

SkillSpector solves the install-time problem and only that. A clean score says "nothing suspicious found before install" — it never says "this skill is safe forever."

The scanner reads the bundle without running it. It deliberately does not cover runtime sandboxing, your agent's permission model, or how to write secure skills — Rushi's review names these as adjacent problems the tool leaves alone. Pair the scan with your agent's own permission controls, and for anything above a LOW score, keep a human in the loop.

As your agent collection grows, the scan becomes part of the onboarding routine for every new skill — one habit that protects the whole coding-agent workflow in our Aider beginner guide and everything you bolt onto it.

Sources

• NVIDIA Skill Documentation — "Scan Agent Skills Before Installation" (docs.nvidia.com/skills/scanning-agent-skills), read 2026-11-03: the scanner's definition, install path, scan commands, output formats, static-vs-semantic analysis, provider configuration, OSV.dev lookup with offline fallback, and the SkillEvaluator Tier 1 relationship.
• digisoulhub.com — "NVIDIA SkillSpector: scan AI agent skills before installing" (README and API checked October 27, 2026): 71-pattern/17-category count at check date, v2.13.1 release (October 23), the uv tool install path, download and zip caps, MCP mode, Pi and OpenCode extensions, Claude Code/Codex CLI/Gemini CLI/MCP coverage.
• rushis.com — "Scanning agent skills before you trust them: a look at NVIDIA SkillSpector": the pdf-formatter exfiltration example, provider options (build.nvidia.com default, OpenAI, Anthropic, Ollama/vLLM/llama.cpp via OPENAI_BASE_URL), SARIF for CI, and the limits (no runtime sandboxing, no permission-model coverage).
• stevetan.com — "The SkillSpector Install Gate": the uv tool install quick-start, the 0–100 score bands with recommendations, the --no-llm + --fail-on-incomplete discipline, and the OSV.dev metadata caveat.
• opusjake.ai — "Skill Scanner": the one-command install, the existing-skills-first scan habit, the MCP server setup (claude mcp add skillspector), the Docker path, and the scan_skill tool contract.

Frequently Asked Questions

Is NVIDIA SkillSpector free?

Yes. It is open-source under the Apache 2.0 license, and the static scan needs no account and no API key. The semantic LLM pass is the only part with a cost: you bring your own provider — an OpenAI, Anthropic, or NVIDIA build.nvidia.com key, or a free local model through Ollama.

Which agents' skills can it scan?

Skills for Claude Code, Codex CLI, Gemini CLI, and MCP, per the project's README. Since it accepts folders, single files, repos, and zips, any skill that follows the standard skill-bundle layout is in scope.

Does SkillSpector need an API key to work?

No for the static half of the job — install it with uv tool install and scan offline with --no-llm, no key involved. A key (or a local Ollama endpoint) is only required when you turn on the semantic LLM pass.

Is a clean scan a guarantee that a skill is safe?

No. SkillSpector checks the skill at install time without running it — it does not cover what the skill does at runtime, how you configure your agent's permissions, or who authored the skill. Treat a clean score as "nothing suspicious found," and pair the habit with tight agent permissions.

What is the difference between SkillSpector and SkillEvaluator?

SkillSpector is the security tier (Tier 1) inside NVIDIA's SkillEvaluator. Scanning determines whether a skill is safe to install; evaluation determines whether the skill improves an agent's output. Use the scanner when reviewing a skill before installing it; use the evaluator when preparing a skill for publication.