How to Enable LLM Semantic Analysis in SkillSpector: A Complete Configuration Guide

Enable LLM semantic analysis in SkillSpector by installing the optional OpenAI or Anthropic provider packages, exporting the corresponding API key, and mapping the three semantic analyzer IDs—semantic_security_discovery, semantic_developer_intent, and semantic_quality_policy—to specific models via the --model-config CLI flag or the SKILLSPECTOR_MODEL_CONFIG environment variable.

SkillSpector is NVIDIA's open-source security analysis framework that extends traditional static analysis with natural language understanding. Activating LLM semantic analysis in SkillSpector unlocks three specialized analyzers capable of detecting intent-level risks and semantic policy violations that rule-based tools miss. This guide covers the exact configuration steps, model mapping hierarchy, and source code locations required to activate these LLM-powered nodes.

Understanding the Semantic Analyzer Nodes

SkillSpector implements three LLM-driven semantic analyzers registered in src/skillspector/nodes/analyzers/__init__.py:

• semantic_security_discovery: Detects intent-level security risks requiring natural language understanding (e.g., malicious prompt patterns)
• semantic_developer_intent: Validates that a skill's natural-language description matches its implementation behavior
• semantic_quality_policy: Enforces policy-level semantic quality checks

These nodes are orchestrated by the meta_analyzer in src/skillspector/meta_analyzer.py and rely on the provider abstractions in src/skillspector/providers/openai/provider.py and src/skillspector/providers/anthropic/provider.py.

Prerequisites for LLM Semantic Analysis

Install Optional LLM Dependencies

Before running semantic analysis, install the required provider packages:

pip install -r requirements.txt  # includes openai, anthropic, etc.

The provider implementations reside in src/skillspector/providers/, with specific clients for OpenAI and Anthropic located at src/skillspector/providers/openai/provider.py and src/skillspector/providers/anthropic/provider.py.

Configure API Credentials

SkillSpector reads provider credentials from standard environment variables. Export the key for your chosen provider:

export OPENAI_API_KEY="sk-..."       # For OpenAI models

export ANTHROPIC_API_KEY="sk-..."    # For Anthropic models

Never commit these keys to version control; the framework reads them at runtime without storing them in the repository state.

Configuring the Model Mapping

The semantic analyzers select their LLM via a hierarchical lookup against the state["model_config"] dictionary. According to the implementation in src/skillspector/nodes/analyzers/semantic_security_discovery.py, semantic_developer_intent.py, and semantic_quality_policy.py, the resolution follows this priority:

model_config = state.get("model_config") or {}
model = (
    model_config.get(ANALYZER_ID)      # 1. Analyzer-specific ID (e.g., "semantic_security_discovery")

    or model_config.get("default")     # 2. Repository-wide default key

    or _SKILLSPECTOR_DEFAULT_MODEL     # 3. Hard-coded fallback constant

)

To enable semantic analysis, you must provide a model mapping for at least the three semantic analyzer IDs.

Activation Methods

CLI Flag Configuration

Pass a JSON mapping directly via the --model-config flag in src/skillspector/cli.py:

skillspector \
  --input ./my_skill \
  --output ./report.sarif \
  --model-config '{"semantic_security_discovery":"gpt-4o","semantic_developer_intent":"claude-2.1","semantic_quality_policy":"gpt-4o"}'

Environment Variable Configuration

Alternatively, set the SKILLSPECTOR_MODEL_CONFIG environment variable with the same JSON structure:

export SKILLSPECTOR_MODEL_CONFIG='{"semantic_security_discovery":"gpt-4o","semantic_developer_intent":"claude-2.1","semantic_quality_policy":"gpt-4o"}'
skillspector --input ./my_skill --output ./report.sarif

Programmatic Configuration

When using the Python API, populate state["model_config"] before invoking the meta-analyzer:

from skillspector import graph

state = {
    "file_cache": {"SKILL.md": "# My Skill"},

    "model_config": {
        "semantic_security_discovery": "gpt-4o",
        "semantic_developer_intent": "claude-2.1",
        "semantic_quality_policy": "gpt-4o",
        "default": "gpt-4o",
    },
}

analysis = graph.build(state)
report = analysis.run()

Running SkillSpector with Semantic Analysis Enabled

Once configured, execute the analysis. The meta_analyzer will invoke the LLM through the appropriate provider (src/skillspector/providers/base.py → concrete provider) and parse the response into SARIF findings alongside static and behavioral analyzers.

# Install dependencies

pip install "openai>=1.0" "anthropic>=0.2"

# Export credentials

export OPENAI_API_KEY="sk-..."

# Run with semantic analysis enabled

skillspector \
  --input ./skill_directory \
  --model-config '{"semantic_security_discovery":"gpt-4o","semantic_developer_intent":"gpt-4o","semantic_quality_policy":"gpt-4o"}' \
  --output ./analysis.sarif

Summary

• LLM semantic analysis in SkillSpector requires three components: provider dependencies, API credentials, and a model-to-analyzer mapping.
• The three semantic analyzers (semantic_security_discovery, semantic_developer_intent, semantic_quality_policy) are registered in src/skillspector/nodes/analyzers/__init__.py.
• Model selection follows a strict hierarchy: analyzer-specific ID → "default" key → _SKILLSPECTOR_DEFAULT_MODEL fallback.
• Activate via --model-config CLI flag, SKILLSPECTOR_MODEL_CONFIG environment variable, or the state["model_config"] dictionary in Python.
• Provider implementations in src/skillspector/providers/openai/provider.py and src/skillspector/providers/anthropic/provider.py handle the actual LLM communication.

Frequently Asked Questions

Which LLM providers does SkillSpector support for semantic analysis?

SkillSpector supports OpenAI and Anthropic providers out of the box, with client implementations located in src/skillspector/providers/openai/provider.py and src/skillspector/providers/anthropic/provider.py. You can configure any model available through these providers (e.g., gpt-4o, claude-2.1) by mapping the analyzer ID to the model name in the model configuration.

What happens if I don't specify a model for a semantic analyzer?

If a specific analyzer ID is missing from the model configuration, the framework falls back to the "default" key in the model config, then to the _SKILLSPECTOR_DEFAULT_MODEL constant defined in the source. If no valid model is resolved, the semantic analyzer will fail to initialize or skip execution, depending on the error handling in src/skillspector/meta_analyzer.py.

Can I use different models for different semantic analyzers?

Yes. The model_config dictionary supports per-analyzer mappings. You can assign gpt-4o to semantic_security_discovery while using claude-2.1 for semantic_developer_intent by specifying separate entries in the JSON configuration passed via --model-config or the SKILLSPECTOR_MODEL_CONFIG environment variable.

Where is the semantic analyzer registry defined?

The three semantic analyzers are registered in src/skillspector/nodes/analyzers/__init__.py. This registry is imported by the meta_analyzer in src/skillspector/meta_analyzer.py, which orchestrates the execution of all analyzers including the LLM-powered semantic nodes.

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