How to Debug SkillSpector Scan Failures with Verbose Logging

Enable the --verbose flag or set SKILLSPECTOR_LOG_LEVEL=DEBUG to expose detailed execution traces, node transitions, and error stack traces from the LangGraph workflow.

When a scan fails in NVIDIA SkillSpector—whether it crashes with a non-zero exit code, fails to resolve an input path, or returns unexpected risk scores—the fastest way to diagnose the issue is to inspect the internal execution flow. SkillSpector uses a structured logging system that captures every step of the analysis pipeline, from input resolution to LLM provider calls. Verbose logging reveals exactly which node in the graph failed and why.

How Verbose Logging Works in SkillSpector

The CLI Verbose Flag

In src/skillspector/cli.py, the scan command defines a --verbose (or -V) option. When invoked, the CLI calls set_level("DEBUG") from the logging module, raising the root logger’s level from WARNING to DEBUG. This single call propagates verbose output across all modules in the package.

skillspector scan ./my-skill --verbose

Centralized Logging Configuration

The logging infrastructure lives in src/skillspector/logging_config.py. The get_logger(__name__) function returns a package-scoped logger (format: skillspector.<module>) configured once per process. When the level is set to DEBUG, every handler emits detailed messages, ensuring that modules like skillspector.nodes.resolve_input or skillspector.nodes.analyzers.static_yara output their internal state.

All primary nodes—including resolve_input, build_context, each analyzer, meta_analyzer, and report—obtain their loggers via get_logger(__name__). Consequently, enabling verbose mode surfaces granular details about file handling, YARA rule compilation, and LLM API interactions.

Understanding the Scan Execution Flow

SkillSpector executes scans as a LangGraph workflow. The CLI builds an initial state dictionary (_scan_state) and invokes the compiled graph via graph.invoke(state, config=trace_config) in src/skillspector/cli.py. The graph wires nodes in a deterministic order: resolve input → build context → run analyzers → meta-analysis → generate report.

Debug logs reveal the exact sequence of node invocations and intermediate state payloads. When an exception occurs, the graph’s exception handling prints the full traceback alongside the node name in the log prefix (e.g., skillspector.nodes.analyzers.static_yara), making it trivial to pinpoint the failure point.

Common Failure Patterns and Debug Log Analysis

Verbose output exposes specific error categories:

• File-not-found or bad URL: Look for "Error loading..." messages in resolve_input node logs at DEBUG level.
• YARA rule compilation errors: The build_context node logs "Failed to compile YARA rule..." with the offending file path.
• LLM provider misconfiguration: Provider modules emit "Provider missing API key" or HTTP error details from files in src/skillspector/providers/.
• Analyzer exceptions: Individual analyzers under src/skillspector/nodes/analyzers/ print tracebacks when unexpected errors occur.
• Non-zero exit codes: The CLI prints the final risk_score before calling raise typer.Exit(code=1); debug logs show the score calculation and any intermediate warnings.

Enabling Debug Logging

Using the Command-Line Flag

The most direct method to debug SkillSpector scan failures with verbose logging is the --verbose flag:

skillspector scan ./my-skill --verbose

You will see output similar to:

DEBUG [skillspector.graph] Scan started: input_path=./my-skill, format=terminal, use_llm=True
DEBUG [skillspector.nodes.resolve_input] Resolving input path ./my-skill …
DEBUG [skillspector.nodes.build_context] Loading YARA rules from /usr/share/skillspector/yara …
DEBUG [skillspector.nodes.analyzers.static_yara] Running YARA scan on 12 files …
DEBUG [skillspector.providers.openai.provider] Calling OpenAI API model=gpt-4 …

Using Environment Variables

If you cannot modify the command line (e.g., when SkillSpector is invoked by another script), set the SKILLSPECTOR_LOG_LEVEL environment variable. The src/skillspector/logging_config.py file reads this variable during initialization, treating DEBUG the same as the --verbose flag.

export SKILLSPECTOR_LOG_LEVEL=DEBUG
skillspector scan ./my-skill

Or inline:

SKILLSPECTOR_LOG_LEVEL=DEBUG skillspector scan https://github.com/example/bad-skill

Capturing Logs to File

To analyze failures offline, redirect stderr to a file:

skillspector scan ./my-skill --verbose 2>debug.log

Then filter for specific nodes:

grep "static_yara" debug.log
grep "resolve_input" debug.log

Key Source Files for Debugging

File	Role
src/skillspector/cli.py	CLI definition, handles --verbose, builds _scan_state, and invokes the graph
src/skillspector/logging_config.py	Central logging configuration, reads SKILLSPECTOR_LOG_LEVEL
src/skillspector/graph.py	Constructs the LangGraph workflow with all analyzer nodes
src/skillspector/nodes/resolve_input.py	Resolves file paths, URLs, and ZIP archives
src/skillspector/nodes/build_context.py	Loads YARA rules and prepares analysis context
src/skillspector/nodes/analyzers/*.py	Individual analyzers (e.g., static_yara.py)
src/skillspector/providers/*	LLM provider implementations (OpenAI, Anthropic, NVIDIA)

Summary

• Enable verbose mode with --verbose or SKILLSPECTOR_LOG_LEVEL=DEBUG to raise the logger level from WARNING to DEBUG.
• Trace the execution flow through the LangGraph workflow, watching state transitions between resolve_input, build_context, analyzers, and meta_analyzer.
• Identify failure points by examining node-specific log prefixes and stack traces in the debug output.
• Capture output to files for offline analysis using shell redirection.

Frequently Asked Questions

How do I enable verbose logging in SkillSpector?

Add the --verbose (or -V) flag to any skillspector scan command. This calls set_level("DEBUG") in src/skillspector/cli.py, which configures the root logger to emit DEBUG-level messages from all nodes and providers.

What does the SKILLSPECTOR_LOG_LEVEL environment variable do?

Setting SKILLSPECTOR_LOG_LEVEL=DEBUG before running SkillSpector achieves the same effect as --verbose. The src/skillspector/logging_config.py module checks this variable during startup and configures the logger accordingly, making it useful when you cannot modify the command line directly.

Where are the analyzer logs located in SkillSpector?

SkillSpector does not write logs to disk by default; they stream to stderr. To save analyzer logs, run the scan with verbose mode and redirect stderr to a file: skillspector scan ./project --verbose 2>logs.txt. The analyzers in src/skillspector/nodes/analyzers/ emit logs under the skillspector.nodes.analyzers namespace.

How can I debug a specific analyzer node failure?

Enable verbose logging and grep the output for the specific analyzer name (e.g., grep "static_yara" or grep "meta_analyzer"). The debug output includes the full traceback and the node name prefix (e.g., skillspector.nodes.analyzers.static_yara), allowing you to isolate whether the failure stems from YARA compilation, LLM API calls, or state handling.

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