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

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

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:

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

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 defines available CLI options
• Format selection propagates via state["output_format"] through the execution graph
• 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), 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 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) 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 ensures that unattended scans produce machine-parseable results for downstream automation.

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