# SkillSpector Output Formats: JSON vs SARIF vs Markdown vs Terminal

> Explore SkillSpector output formats: JSON, SARIF, Markdown, & Terminal. Understand each format's use case to streamline your security scanning and reporting workflows.

- Repository: [NVIDIA Corporation/SkillSpector](https://github.com/NVIDIA/SkillSpector)
- Tags: deep-dive
- Published: 2026-06-25

---

**SkillSpector generates security scan reports in four distinct formats—JSON for programmatic consumption, SARIF for IDE integration, Markdown for documentation, and Terminal for human-readable CLI output—controlled via the `--format` flag or `output_format` API parameter.**

NVIDIA/SkillSpector is an AI skill security scanner that supports multiple output serialization strategies to fit diverse consumption patterns. Whether you need machine-readable data for CI automation or standardized SARIF for GitHub Code Scanning, SkillSpector's output formats adapt to your workflow requirements.

## Understanding SkillSpector Output Format Architecture

The reporting logic resides in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py), where the system inspects `state["output_format"]` to determine serialization strategy. If unset, the code defaults to `"sarif"` (line 555), though the CLI may override this for interactive terminal sessions.

Each format serves a distinct consumption pattern:
- **JSON** for lightweight machine parsing
- **SARIF** for industry-standard tool integration
- **Markdown** for documentation platforms
- **Terminal** for interactive human review

## JSON: Lightweight Machine-Readable Payloads

Use **JSON** output when integrating SkillSpector into CI pipelines, Python scripts, or downstream automation tools that require structured data without schema overhead.

In [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py) (lines 588-602), the `Report` model serializes via `model_dump(mode="json")`, producing a document containing `risk_score`, severity levels, findings metadata, and rule identifiers.

```bash
skillspector scan ./my_skill --format json --no-llm > report.json

```

Programmatically:

```python
from skillspector.mcp_server import run_scan

result = await run_scan(
    target="./my_skill",
    use_llm=False,
    output_format="json"
)

import json
report = json.loads(result["report_body"])
print(report["risk_score"], report["findings"][0]["rule_id"])

```

## SARIF: Industry-Standard Static Analysis Integration

The **SARIF** (Static Analysis Results Interchange Format) 2.1.0 output enables seamless integration with GitHub Code Scanning, Azure DevOps, VS Code, and other SARIF-compliant platforms.

The `_build_sarif` function (line 511 in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py)) constructs a standards-compliant log containing rules, physical locations, and optional suppressions. This is the default format when `output_format` remains unspecified.

```bash
skillspector scan ./my_skill --format sarif --output findings.sarif

```

Programmatically:

```python
result = await run_scan("./my_skill", output_format="sarif")
with open("sarif_report.json", "w") as f:
    f.write(result["report_body"])

# Upload to GitHub Code Scanning or Azure DevOps

```

## Markdown: Documentation-Ready Reports

Select **Markdown** output to generate human-readable reports suitable for GitHub pull request comments, Confluence pages, JIRA tickets, or committed security documentation.

The rendering logic (lines 602-620 in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py)) produces structured headings, tables, and bullet lists that render natively in most documentation platforms.

```bash
skillspector scan ./my_skill --format markdown > SECURITY_REPORT.md

```

## Terminal: Interactive CLI Visualization

The **Terminal** format leverages the Rich library to display color-coded tables and panels via `_format_terminal` (line 540 in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py)).

This format targets interactive development sessions where developers need immediate visual feedback without leaving the command line. When running the Typer-based CLI interactively, this format provides instant readability through syntax highlighting and severity-based color coding.

```bash
skillspector scan ./my_skill

```

## Validating and Selecting Output Formats

SkillSpector validates format selection before execution begins. In [`src/skillspector/mcp_server.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py) (lines 74-75), the server checks requested formats against `VALID_FORMATS`, raising a descriptive `ValueError` for unsupported values.

The Typer CLI in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) (line 130) forwards the `--format` flag value directly into the workflow state as `state["output_format"]`, making format selection transparent across interfaces.

## Summary

- **JSON**: Best for CI pipelines and programmatic consumption requiring lightweight, schema-flexible data from `model_dump(mode="json")`.
- **SARIF**: The default format for IDE integration, GitHub Code Scanning, and compliance with static analysis tooling standards via `_build_sarif`.
- **Markdown**: Ideal for documentation generators, PR comments, and knowledge bases that render markdown natively.
- **Terminal**: Optimized for interactive CLI usage with Rich-powered color coding and immediate visual feedback via `_format_terminal`.

## Frequently Asked Questions

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

When unspecified, `state["output_format"]` defaults to `"sarif"` (line 555 in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py)). However, the CLI may present terminal-formatted output for interactive sessions while still generating SARIF internally for programmatic access.

### Can SkillSpector output formats be used in automated CI/CD pipelines?

Yes, **JSON** and **SARIF** formats are specifically designed for automation. JSON provides lightweight parsing for custom scripts, while SARIF integrates natively with GitHub Actions, Azure DevOps, and other platforms that consume static analysis results.

### How does the SARIF format improve security review workflows?

SARIF 2.1.0 compliance allows findings to appear directly in your IDE code view and GitHub Code Scanning alerts, leveraging standardized rule metadata and physical location mapping from `_build_sarif` in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py).

### What happens if I specify an unsupported output format?

The system validates formats against `VALID_FORMATS` in [`src/skillspector/mcp_server.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py) (lines 74-75) and raises a `ValueError` with a descriptive message before the scan initiates, preventing runtime serialization errors.