How to Install SkillSpector: CLI, Source, and Docker Setup Guide

SkillSpector can be installed via the uv package manager as a standalone CLI tool, cloned and built from source for development, or deployed as a Docker container requiring no local Python runtime.

This guide covers the three primary installation methods for the NVIDIA/SkillSpector repository, a Python-based security scanner for AI-agent skills. Each approach targets different use cases, from quick command-line usage to integration into CI/CD pipelines.

Install the CLI Tool with uv (Quickest Method)

The fastest way to install SkillSpector uses the uv tool to create an isolated executable directly from the Git repository without cloning.

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

This command downloads the package and installs the skillspector console script defined in [pyproject.toml → [project.scripts]](https://github.com/NVIDIA/SkillSpector/blob/main/pyproject.toml#L67-L69), which points to skillspector.cli:app. The uv tool manages its own isolated environment, eliminating the need for manual virtual environment setup.

To upgrade later, run:

uv tool update skillspector

Optional MCP Server Support

If you need the Model Context Protocol (MCP) server for agent integration, install the extra dependency:

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

Install from Source for Development

For contributing to the project, running the test suite, or inspecting the source code, clone the repository and use the provided Makefile targets.

git clone https://github.com/NVIDIA/skillspector.git
cd skillspector

# Create a virtual environment (uv preferred)

uv venv .venv && source .venv/bin/activate

# Alternatively: python3 -m venv .venv && source .venv/bin/activate

Install the production dependencies:

make install

For development work that includes testing and linting tools:

make install-dev

These targets parse the dependency declarations in [pyproject.toml](https://github.com/NVIDIA/SkillSpector/blob/main/pyproject.toml), specifically the [project] and [project.optional-dependencies] sections, ensuring all required packages are present.

Run SkillSpector via Docker

SkillSpector ships a minimal Dockerfile based on python:3.12-slim-bookworm for environments where you cannot install Python locally.

Build the image using the Makefile:

make docker-build

Run a scan against a local skill directory by mounting it as a volume:

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

Pass environment variables such as LLM API credentials using --env-file or -e flags as documented in the repository README.

Verify Your Installation

Confirm the binary is correctly installed and accessible:

skillspector --version

# Expected output: SkillSpector v2.3.11 (or similar)

Test the full pipeline by scanning a sample skill:

# Full analysis with LLM

skillspector scan ./tests/fixtures/malicious_skill/

# Static analysis only (faster)

skillspector scan ./tests/fixtures/malicious_skill/ --no-llm

Use SkillSpector as a Python Library

Beyond the CLI, you can import SkillSpector directly into Python applications to leverage the LangGraph workflow programmatically.

from skillspector.graph import graph

# Execute the analysis workflow

result = graph.invoke({
    "input_path": "./my-skill/",
    "output_format": "json",
    "use_llm": True,
})

# Access the risk assessment

print(f"Score: {result['risk_assessment']['score']}")
print(f"Severity: {result['risk_assessment']['severity']}")

# Iterate through findings

for finding in result["issues"]:
    print(f"[{finding['severity']}] {finding['rule_id']}: {finding['message']}")

The graph object defined in src/skillspector/graph.py orchestrates the analysis nodes, while src/skillspector/state.py manages the mutable scan context passed between components.

Summary

• uv tool install provides the fastest path to a working CLI without manual environment management.
• Source installation via make install or make install-dev is required for development, testing, and CI pipelines.
• Docker deployment eliminates Python version conflicts and is ideal for containerized workflows.
• The MCP extra (skillspector[mcp]) enables agent integration via the Model Context Protocol.
• Core entry points reside in src/skillspector/cli.py, with the workflow engine located in src/skillspector/graph.py.

Frequently Asked Questions

What is the fastest way to install SkillSpector?

The uv tool install method is fastest. Run uv tool install git+https://github.com/NVIDIA/skillspector.git to create an isolated executable without cloning the repository or managing virtual environments manually.

Do I need Python installed to use SkillSpector?

No, if you use the Docker method. The provided Dockerfile based on python:3.12-slim-bookworm bundles all dependencies, allowing you to run scans via docker run commands without a local Python installation. However, the CLI and source methods require Python 3.12 or later.

How do I install the optional MCP server support?

Install the mcp extra using either uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git' for CLI usage, or pip install -e '.[mcp]' when installing from source. This exposes the scan_skill tool via src/skillspector/mcp_server.py for agent integration.

Can I run SkillSpector without LLM analysis?

Yes. Append the --no-llm flag to any scan command to skip the semantic analysis phase and run only the static analyzers. This executes faster and requires no API keys, though it may miss context-dependent vulnerabilities that the LLM component detects.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}