SkillSpector Output Formats: JSON vs SARIF vs Markdown vs Terminal

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, 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 (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.

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

Programmatically:

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) constructs a standards-compliant log containing rules, physical locations, and optional suppressions. This is the default format when output_format remains unspecified.

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

Programmatically:

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) produces structured headings, tables, and bullet lists that render natively in most documentation platforms.

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).

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.

skillspector scan ./my_skill

Validating and Selecting Output Formats

SkillSpector validates format selection before execution begins. In 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 (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). 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.

What happens if I specify an unsupported output format?

The system validates formats against VALID_FORMATS in src/skillspector/mcp_server.py (lines 74-75) and raises a ValueError with a descriptive message before the scan initiates, preventing runtime serialization errors.

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