# SkillSpector Output Formats: JSON, SARIF, Markdown, and Terminal Reports

> Explore SkillSpector's output formats: JSON, SARIF, Markdown, and terminal. Learn how to configure your reports using the CLI flag or state key for efficient analysis. Get started now.

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

---

**SkillSpector supports four distinct output formats—terminal, JSON, Markdown, and SARIF—all configurable via the `--format` CLI flag or `output_format` state key, with SARIF serving as the default.**

NVIDIA SkillSpector is an open-source security scanner for AI skills that delivers findings through multiple serialization options. Understanding these SkillSpector output formats allows you to integrate scan results into console workflows, documentation pipelines, or automated security tooling.

## Supported Format Options

SkillSpector defines its available output modes in the **`FormatChoice`** enum located in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) (lines 51-58). The tool supports:

- **Terminal** – Rich-formatted console output with colorized styling for human review
- **JSON** – Machine-readable structured data for downstream processing
- **Markdown** – GitHub-friendly formatting suitable for documentation and pull request comments
- **SARIF** – Static Analysis Results Interchange Format, the OASIS standard for static analysis tools

When running scans, the CLI maps the `--format` argument (or `-f` shorthand) to this enum, propagating the selection through the execution graph.

## Report Generation Architecture

The core formatting logic resides in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py). During execution, the report node reads `state["output_format"]` (lines 60-62), defaulting to `"sarif"` when no explicit choice is provided.

Based on this state value, SkillSpector invokes one of four private formatter methods:

- **`_format_terminal`** (lines 41-78) – Renders colorized tables and severity indicators using rich styling
- **`_format_json`** (lines 81-120) – Serializes findings into a compact JSON string
- **`_format_markdown`** (lines 122-160) – Generates Markdown tables compatible with GitHub rendering
- **`_build_sarif`** – Constructs SARIF output using data models from [`src/skillspector/sarif_models.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/sarif_models.py)

Each formatter receives the scan results and returns a string stored in `result["report_body"]`, which the CLI then writes to stdout or a file.

## CLI Usage Examples

Select your desired SkillSpector output format using the `--format` flag:

```bash

# Terminal output (human-readable, colorized)

skillspector scan ./my-skill/ --format terminal

# JSON export for programmatic parsing

skillspector scan ./my-skill/ --format json > security-report.json

# Markdown for documentation or GitHub issues

skillspector scan ./my-skill/ --format markdown > findings.md

# SARIF (default) for ingestion into security platforms

skillspector scan ./my-skill/ --format sarif > results.sarif

```

If you omit the `--format` flag, SkillSpector automatically defaults to SARIF output, ensuring compatibility with standard static analysis result viewers.

## Programmatic API Integration

You can invoke these output formats directly from Python when embedding SkillSpector into custom workflows:

```python
from skillspector.cli import _scan_state, FormatChoice
from skillspector.graph import graph

# Configure scan with JSON output

state = _scan_state(
    "path/to/skill", 
    FormatChoice.json,  # Or: terminal, markdown, sarif

    no_llm=False
)

result = graph.invoke(state)
print(result["report_body"])  # JSON string ready for parsing

```

The `FormatChoice` enum provides type-safe selection of serialization strategies, while the graph's state dictionary carries the `output_format` value through to the report node.

## Summary

- SkillSpector supports **four output formats**: terminal, JSON, Markdown, and SARIF
- The **`FormatChoice`** enum in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) defines available CLI options
- Format selection propagates via `state["output_format"]` through the execution graph
- **[`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py)** contains four dedicated formatter methods for each output type
- **SARIF is the default** format, aligning with industry standards for static analysis reporting
- All formats are accessible via `--format` CLI flag or programmatic `FormatChoice` enumeration

## Frequently Asked Questions

### What is the default output format for SkillSpector?

SARIF is the default output format. When you run `skillspector scan` without specifying a `--format` flag, the tool automatically sets `output_format` to `"sarif"` in the execution state (lines 60-62 in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py)), generating a Static Analysis Results Interchange Format document compatible with GitHub Advanced Security and other SARIF consumers.

### How do I export SkillSpector results to JSON?

Pass the `--format json` flag (or `-f json`) when running the scan command, then redirect the output to a file: `skillspector scan ./skill-path/ --format json > report.json`. Alternatively, use the Python API with [`FormatChoice.json`](https://github.com/NVIDIA/SkillSpector/blob/main/FormatChoice.json) to retrieve the JSON string directly from `result["report_body"]` without writing to disk.

### Can SkillSpector generate GitHub-compatible Markdown reports?

Yes. SkillSpector includes a dedicated `_format_markdown` method (lines 122-160 in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py)) that renders findings as Markdown tables. Use `--format markdown` to produce output suitable for pasting into GitHub issues, pull request descriptions, or wiki pages while preserving severity indicators and code references.

### Why does SkillSpector use SARIF as the default instead of terminal output?

SARIF serves as the de-facto standard for static analysis interchange, enabling seamless integration with security dashboards, CI/CD gates, and vulnerability management platforms. While terminal output (`_format_terminal`) provides immediate human readability, the default SARIF behavior in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py) ensures that unattended scans produce machine-parseable results for downstream automation.