# How to Run SkillSpector Using Docker: A Complete Setup Guide

> Learn to run SkillSpector using Docker. This guide shows you how to build a multi-stage image for easy scanning without local Python installation.

- Repository: [NVIDIA Corporation/SkillSpector](https://github.com/NVIDIA/SkillSpector)
- Tags: how-to-guide
- Published: 2026-06-14

---

**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**

```bash
docker build -t skillspector .

```

**Option 2: Makefile shortcut**

```bash
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`](https://github.com/NVIDIA/SkillSpector/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

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

```

The file [`report.json`](https://github.com/NVIDIA/SkillSpector/blob/main/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:

```bash
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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/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.