How to Get SkillSpector Output in JSON or SARIF Format

Use the --format flag with skillspector scan to select json or sarif, and optionally specify --output to write to a file instead of stdout.

NVIDIA's SkillSpector analyzes AI skills for potential issues and can export findings in machine-readable formats. The command-line interface supports both JSON and SARIF (Static Analysis Results Interchange Format) outputs through a configurable report generation system. This guide covers the exact CLI arguments and implementation details found in the source code to help you integrate SkillSpector into automated workflows.

Command-Line Format Selection

The skillspector scan command accepts a --format option that controls the output serialization. According to the CLI implementation in src/skillspector/cli.py, the tool defines a FormatChoice enum supporting terminal, json, markdown, and sarif values.

When you run a scan, the report node (src/skillspector/nodes/report.py) reads the output_format from the execution state. If omitted, it defaults to SARIF. The node then either serializes the raw Python dictionary as JSON or constructs a SARIF 2.1.0 document via the _build_sarif method.

Writing to Files vs. STDOUT

The CLI uses the _write_result helper to handle output destination. If you provide --output /path/to/file, the content writes to that path using Path(output).write_text. Without --output, the report prints to the console.

Generating JSON Output

To export findings as formatted JSON, pass --format json. The report node calls json.dumps(..., indent=2) on the internal result dictionary, producing a human-readable JSON structure suitable for custom parsing pipelines.

skillspector scan ./my-skill/ \
    --format json \
    --output report.json

If you omit --output, the JSON streams to stdout for piping.

Generating SARIF Output

SARIF is the default format when no --format is specified. The implementation in src/skillspector/nodes/report.py constructs a standards-compliant SARIF 2.1.0 object through the _build_sarif method, which includes rules metadata, driver information, and findings locations. The payload is validated against the official schema using skillspector.sarif_models.validate_sarif_report before output.

skillspector scan ./my-skill/ \
    --format sarif \
    --output findings.sarif

This file integrates with GitHub Code Scanning, VS Code extensions, and other SARIF-compatible tools.

SARIF with Baseline Suppressions

When using --baseline to compare against previous scans, suppressed findings appear in the SARIF output with "suppressions": [{"kind": "external"}] annotations, as verified in tests/nodes/test_report.py.

skillspector scan ./my-skill/ \
    --baseline baseline.yaml \
    --format sarif \
    --output sarif-with-baseline.sarif

Implementation Architecture

Understanding the code flow helps troubleshoot format issues:

• CLI Parsing (src/skillspector/cli.py): Defines FormatChoice enum and --format / --output arguments
• Report Generation (src/skillspector/nodes/report.py): Contains _build_sarif and JSON serialization logic
• Validation (src/skillspector/sarif_models.py): Houses validate_sarif_report and the SARIF schema URI

Summary

• Use --format json or --format sarif with skillspector scan to select your output format
• SARIF is the default when --format is omitted
• Specify --output filename to write to disk; omit it to print to stdout
• SARIF output is validated against the 2.1.0 schema via validate_sarif_report
• Baseline comparisons include suppression metadata in SARIF outputs

Frequently Asked Questions

What is the default output format for SkillSpector?

The report node defaults to SARIF format when the --format argument is not provided, as implemented in src/skillspector/nodes/report.py where the output_format field falls back to the SARIF builder.

Can I pipe SkillSpector output directly to other tools?

Yes. Omit the --output flag to stream the JSON or SARIF payload to stdout. This allows direct piping to tools like jq for JSON parsing or submission to security dashboards via command pipelines.

How does SkillSpector validate SARIF output?

The tool calls skillspector.sarif_models.validate_sarif_report after generating the payload in src/skillspector/nodes/report.py. This ensures the output conforms to the official SARIF 2.1.0 schema before writing to disk or stdout.

Does the JSON format include the same information as SARIF?

Yes. The JSON output contains the raw Python dictionary of findings with identical data to the SARIF version, just without the SARIF wrapper structure. Both formats include all detected issues, severity levels, and file locations from the scan.

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