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

> Explore SkillSpector output formats: JSON, Markdown, SARIF, and Terminal. Understand how to use the `--format` flag and `output_format` parameter to customize your results.

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

---

**SkillSpector supports four distinct output formats—JSON, Markdown, SARIF, and Terminal—with SARIF set as the default, controlled via the `--format` CLI flag or `output_format` API parameter.**

NVIDIA SkillSpector is an automated code analysis tool designed to evaluate AI skills and agents. When generating reports, the tool provides flexibility in how findings are serialized, supporting both machine-readable standards for CI/CD integration and human-readable formats for manual review.

## Supported Output Formats

SkillSpector can emit analysis results in four distinct formats, each designed for specific consumption patterns:

- **JSON**: A structured document containing the complete list of findings, risk scores, and metadata. Ideal for programmatic processing and custom tooling.
- **Markdown**: Human-readable text with headings, tables, and bullet points optimized for viewing in editors, GitHub, or documentation systems.
- **SARIF**: The Static Analysis Results Interchange Format, a standardized JSON schema widely adopted by CI tools, GitHub Advanced Security, and IDEs for security findings aggregation.
- **Terminal**: A Rich-styled, colorized view designed for interactive command-line usage, providing immediate visual feedback during development.

## How Output Formats Are Defined in the Source Code

The canonical list of valid formats is defined in the MCP server module as a tuple constant:

```python

# src/skillspector/mcp_server.py

VALID_FORMATS = ("json", "markdown", "sarif", "terminal")

```

This tuple is used throughout the codebase to validate format arguments passed via CLI or API calls. The `run_scan` function in [`src/skillspector/mcp_server.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py) checks incoming requests against this tuple to ensure only supported formats are processed.

## Default Format and Configuration

If no format is specified, SkillSpector defaults to **SARIF**. This logic is implemented in the report generation node:

```python

# src/skillspector/nodes/report.py

output_format = state.get("output_format") or "sarif"

```

According to the NVIDIA/SkillSpector source code, this default ensures compatibility with security scanning workflows and GitHub code scanning integration out of the box.

## Using Output Formats in Practice

### Command-Line Interface

The CLI exposes format selection via the `--format` (or `-f`) option defined in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py):

```bash

# Generate JSON report for programmatic processing

skill-spector scan ./my_skill --format json --output report.json

# View formatted Markdown in stdout

skill-spector scan ./my_skill --format markdown

# Use default SARIF output (writes to file)

skill-spector scan ./my_skill --output findings.sarif

# Interactive terminal view with colorized output

skill-spector scan ./my_skill --format terminal

```

### Python API

When invoking scans programmatically, pass the format to the `run_scan` function:

```python
from skillspector.mcp_server import run_scan

# Execute scan with Markdown output

result = await run_scan(
    target="./my_skill",
    use_llm=True,
    output_format="markdown",
)

# Access the report content via report_body

print(result["report_body"])

```

### REST API Integration

The REST endpoint accepts an `output_format` field in the request payload:

```http
POST /scan HTTP/1.1
Content-Type: application/json

{
  "skill_path": "./my_skill",
  "use_llm": true,
  "output_format": "json"
}

```

The response returns a JSON object containing a `report_body` field with the serialized report content.

## Summary

- SkillSpector supports **four output formats**: JSON, Markdown, SARIF, and Terminal, defined in `VALID_FORMATS` in [`src/skillspector/mcp_server.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py).
- **SARIF is the default** format when no option is specified, as implemented in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py).
- The **CLI** accepts `--format` or `-f` flags to select the desired output.
- The **Python API** and **REST endpoints** both accept an `output_format` parameter that maps directly to the valid format tuple.

## Frequently Asked Questions

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

**SARIF** is the default output format. According to the source code in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py), the system defaults to `"sarif"` when the `output_format` state variable is unset or empty, ensuring compatibility with standard security scanning workflows and GitHub code scanning features.

### How do I specify the output format when using the SkillSpector CLI?

Use the `--format` or `-f` flag followed by one of the valid format names. For example, `skill-spector scan ./skill --format json` outputs a JSON file. The CLI parser in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) validates this input against the `VALID_FORMATS` tuple before execution.

### What is SARIF format and why does SkillSpector use it as the default?

**SARIF** (Static Analysis Results Interchange Format) is a standardized JSON schema for static analysis results. SkillSpector uses it as the default because it integrates natively with CI/CD pipelines, GitHub Advanced Security, and most modern IDEs, allowing automated ingestion of security and quality findings without custom parsers.

### Can I generate multiple output formats from a single SkillSpector scan?

The current implementation in [`src/skillspector/mcp_server.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py) processes one format per scan invocation via the `output_format` parameter. To generate multiple formats, you must run the scan command multiple times with different `--format` values, as each format is handled by distinct formatters in the report generation node.