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

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:

# 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 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:

# 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:

# 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:

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:

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.
• SARIF is the default format when no option is specified, as implemented in 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, 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}