How to Run SkillSpector Using Docker: A Complete Setup Guide

You can run SkillSpector using Docker by building a multi-stage image that packages the CLI and its dependencies, then mounting your skill directory to /scan to execute scans without installing Python locally.

NVIDIA's SkillSpector repository provides a streamlined Docker workflow that eliminates local Python setup requirements. By leveraging the multi-stage build defined in the project's Dockerfile, you create a containerized environment that executes the skillspector CLI exactly as it would run natively. This approach lets you analyze skills using static analysis or LLM-assisted scanning while keeping all dependencies isolated inside the container.

Understanding the SkillSpector Docker Architecture

The Dockerfile in the repository root implements a minimal multi-stage build that optimizes image size and security.

Builder Stage

The first stage uses python:3.12-slim-bookworm as the base image to compile dependencies. It copies the project source into the container, creates a Python virtual environment, and installs the package using pip install --no-cache-dir . according to lines 1-8 of the Dockerfile. This stage ensures all static analysis dependencies are resolved and packaged before the final image is assembled.

Runtime Stage

The runtime stage copies the prepared virtual environment from the builder and configures the execution environment. It sets PATH="/app/.venv/bin:$PATH" to ensure the skillspector command is available system-wide, and declares /scan as the working directory (lines 9-15 of the Dockerfile). When you run SkillSpector using Docker, you mount your host directory to this /scan path, allowing the scanner to access your files as if they were local to the container.

Building the SkillSpector Docker Image

You have two options for building the image: direct Docker commands or the provided Makefile shortcut.

Option 1: Direct Docker build

docker build -t skillspector .

Option 2: Makefile shortcut

make docker-build

Both methods tag the resulting image as skillspector and prepare the container entrypoint to invoke the CLI defined in src/skillspector/cli.py.

How to Run SkillSpector Using Docker

Once built, you execute scans by mounting your target directory and passing appropriate flags to the container.

Perform Static Analysis Without LLM

For security scans that do not require LLM analysis, pass the --no-llm flag:

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

This mounts your current working directory to /scan and runs the static analyzer against the specified skill path.

Run LLM-Assisted Scans Using Environment Files

To enable LLM analysis, provide credentials via an .env file mounted into the container:

cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF

docker run --rm \
  -v "$PWD:/scan" \
  --env-file .env \
  skillspector scan ./my-skill/

The scanner reads these variables at runtime from the environment, as implemented in the CLI logic.

Pass Credentials Directly via Environment Variables

Alternatively, inject credentials directly using the -e flag:

docker run --rm \
  -v "$PWD:/scan" \
  -e SKILLSPECTOR_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  skillspector scan ./my-skill/

Export Scan Results to Your Host

When generating reports, write outputs to a file path that exists within the mounted /scan directory so results persist on your host:

docker run --rm \
  -v "$PWD:/scan" \
  skillspector scan ./my-skill/ --format json --output report.json

The file report.json will be available in your current working directory after the container exits.

Create a Persistent Docker Alias

For repeated use, define a shell alias that encapsulates the common flags:

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

Understanding the Container Entrypoint

The container's entrypoint is configured in lines 16-17 of the Dockerfile to invoke the skillspector command directly. This command is implemented in src/skillspector/cli.py and handles all scan logic, argument parsing, and LLM integration. When you run SkillSpector using Docker, you are essentially executing this CLI inside an isolated environment that includes only the necessary static-analysis dependencies.

Summary

• The multi-stage build in Dockerfile uses python:3.12-slim-bookworm to create a minimal runtime image with the skillspector CLI on the system PATH.
• Mount your working directory to /scan when running containers to give SkillSpector access to your skill files.
• Use --no-llm for static-only scans that require no API credentials.
• Provide LLM credentials either via --env-file .env or individual -e environment variables when running LLM-assisted scans.
• Write outputs to paths within /scan to ensure reports are saved to your host filesystem.

Frequently Asked Questions

Do I need Python installed locally to run SkillSpector using Docker?

No. The Docker image contains its own Python 3.12 installation and virtual environment. You only need Docker installed on your host system to build and run the container.

How do I provide API keys when running SkillSpector in Docker?

You can pass API keys using either an environment file (--env-file .env) or direct environment variables (-e VARIABLE_NAME=value). The scanner reads these credentials at runtime from the container's environment, as supported by the implementation in src/skillspector/cli.py.

Where does SkillSpector look for files inside the Docker container?

The container's working directory is set to /scan. When you mount a host directory using -v "$PWD:/scan", the scanner treats your current working directory as the root path for resolving skill locations.

Can I use the Makefile to build the Docker image?

Yes. The repository includes a Makefile with a docker-build target that wraps the docker build -t skillspector . command, providing a convenient shortcut for building the image.

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