# How to Scan Multi-Skill Directories with the --recursive Flag in SkillSpector

> Learn how to scan multi-skill directories using the --recursive flag in SkillSpector. This feature automates batch scanning of multiple skills, detecting sub-directories and running analysis pipelines efficiently.

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

---

**SkillSpector's `--recursive` flag enables batch scanning of multiple independent skills within a single directory by automatically detecting sub-directories containing individual [`SKILL.md`](https://github.com/NVIDIA/SkillSpector/blob/main/SKILL.md) files and executing the analysis pipeline for each one separately.**

NVIDIA's SkillSpector provides a recursive scanning mode that treats directories containing several independent skills as discrete scan targets. When you use the `--recursive` (or `-r`) flag with the `scan` command, the tool automatically identifies multi-skill repositories and executes the analysis pipeline for each sub-skill independently. This capability streamlines security auditing across large skill collections without requiring manual invocation for each individual skill directory.

## Understanding Multi-Skill Directory Detection

According to the detection logic in [`src/skillspector/multi_skill.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/multi_skill.py), SkillSpector distinguishes between single-skill and multi-skill directories based on the presence and location of [`SKILL.md`](https://github.com/NVIDIA/SkillSpector/blob/main/SKILL.md) files.

### The Detection Algorithm

The `detect_skills()` function (lines 51-61 in [`src/skillspector/multi_skill.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/multi_skill.py)) determines whether a target directory qualifies as multi-skill. A directory is classified as **multi-skill** only when it satisfies two conditions simultaneously: it lacks a top-level [`SKILL.md`](https://github.com/NVIDIA/SkillSpector/blob/main/SKILL.md) file, and it contains at least two immediate sub-directories that each contain their own [`SKILL.md`](https://github.com/NVIDIA/SkillSpector/blob/main/SKILL.md) file.

### Single-Skill Override Behavior

If SkillSpector finds a [`SKILL.md`](https://github.com/NVIDIA/SkillSpector/blob/main/SKILL.md) file in the root directory, it treats the entire structure as a **single skill** regardless of nested skill definitions. This design ensures that composite skills or monorepos with a primary skill definition aren't incorrectly fragmented during analysis.

## CLI Implementation and Scanning Logic

### Flag Definition and Entry Point

The `--recursive` option is defined in the CLI at lines 217-224 of [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py). When supplied alongside a directory path, the entry point at lines 80-86 invokes `detect_skills()` to evaluate whether the target requires multi-skill handling.

### Multi-Skill Orchestration

Upon detecting a multi-skill structure (`is_multi_skill=True`), the CLI delegates to `_scan_multi_skill()` (lines 59-66 in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py)). This orchestrator iterates over every detected `SkillDirectory` object and invokes the standard analysis pipeline—`_scan_state` followed by `graph.invoke`—for each sub-skill independently.

Results are collected and optionally consolidated into a combined JSON report when using `--format json` with an `--output` path (lines 94-112).

## Command-Line and Programmatic Usage

SkillSpector supports recursive scanning through both CLI invocation and direct Python API calls.

### Command-Line Examples

Scan a directory containing multiple independent skills:

```bash
skillspector scan ./skill-collection/ --recursive

```

Generate a combined JSON report for all discovered skills:

```bash
skillspector scan ./skill-collection/ --recursive --format json --output multi_report.json

```

### Python API Implementation

```python
from pathlib import Path
from skillspector.multi_skill import detect_skills
from skillspector.cli import _scan_multi_skill, FormatChoice, _scan_state, _build_trace_config
from skillspector.graph import graph  # the LangGraph pipeline

# Path to a directory that may hold many skills

root = Path("./skill-collection/").resolve()

# Detect sub-skills

detection = detect_skills(root)

if detection.is_multi_skill:
    # Run the same logic the CLI uses

    _scan_multi_skill(
        detection=detection,
        format=FormatChoice.json,
        output=Path("multi_report.json"),
        no_llm=False,
        yara_rules_dir=None,
        verbose=True,
    )
else:
    # Fallback to a normal single-skill scan

    state = _scan_state(str(root), FormatChoice.json, no_llm=False)
    result = graph.invoke(state, config=_build_trace_config(str(root), FormatChoice.json, False))
    # …process `result` as needed…

```

## Exit Codes and Risk Aggregation

After completing a multi-skill scan, SkillSpector calculates the process exit code based on the highest risk score discovered across all sub-skills. As implemented in lines 39-41 of [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py), the process returns a failure exit code if any individual skill produces a risk score greater than 50, ensuring that high-severity findings in any sub-skill trigger appropriate CI/CD pipeline failures.

## Summary

- Use `--recursive` to scan directories containing multiple independent skills, each defined by their own [`SKILL.md`](https://github.com/NVIDIA/SkillSpector/blob/main/SKILL.md) file.
- The `detect_skills()` function in [`src/skillspector/multi_skill.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/multi_skill.py) identifies multi-skill structures by checking for the absence of root-level [`SKILL.md`](https://github.com/NVIDIA/SkillSpector/blob/main/SKILL.md) and presence of skill definitions in sub-directories.
- The `_scan_multi_skill()` orchestrator processes each sub-skill independently through the standard `graph.invoke` pipeline.
- Combine `--recursive` with `--format json` and `--output` to generate consolidated reports for entire skill collections.
- Exit codes reflect the highest risk score across all scanned skills, failing if any score exceeds 50.

## Frequently Asked Questions

### What happens if I use --recursive on a single-skill directory?

SkillSpector automatically falls back to standard single-skill scanning mode if the target directory contains a top-level [`SKILL.md`](https://github.com/NVIDIA/SkillSpector/blob/main/SKILL.md) file. According to the logic in [`src/skillspector/multi_skill.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/multi_skill.py), the recursive detection only activates when the directory structure matches the multi-skill criteria of having no root skill file but multiple sub-directory skill definitions.

### Can I customize the risk threshold for exit codes?

The exit code logic in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) (lines 39-41) uses a fixed threshold of 50 for determining scan failure. Any individual skill scoring above this threshold causes the entire multi-skill scan to return a non-zero exit code, regardless of other skills' scores.

### Does the --recursive flag support deeply nested skill discovery?

The current implementation detects immediate sub-directories only. A directory qualifies as multi-skill when at least two direct sub-directories contain [`SKILL.md`](https://github.com/NVIDIA/SkillSpector/blob/main/SKILL.md) files. While the scanning logic processes each detected skill independently, it does not recursively traverse deeper than the immediate sub-directory level for initial discovery purposes.

### How are results combined when using JSON output?

When you specify `--format json` with `--output`, the `_scan_multi_skill()` function aggregates individual scan results into a single JSON file. This combined report contains the analysis data from all discovered skills while maintaining separation between individual skill results for traceability and debugging purposes.