SkillSpector: NVIDIA’s Open-Source Security Scanner for AI Agent Skills #

SkillSpector is a security scanning tool specifically designed for AI agent skills — the modular plugins and extensions that power frameworks like Claude Code, GitHub Copilot, Codex CLI, and Gemini CLI. Developed by NVIDIA with 10,273 GitHub stars, it addresses the growing security concerns around installing unvetted agent skills in production environments.

This article covers installation, scanning capabilities, vulnerability detection, integration with agent frameworks, and best practices for securing AI agent ecosystems.

TL;DR #

As AI agent skills become increasingly popular, so do the security risks of installing unvetted ones. SkillSpector provides automated scanning for over 800 cybersecurity skills, detecting vulnerabilities, malicious patterns, and security risks before they reach your system. It supports all major agent frameworks and provides actionable remediation guidance.

What Is SkillSpector? #

SkillSpector was born from a critical observation: as AI agent skills proliferate across developer workflows, the security surface area expands dramatically. Unlike traditional software packages that undergo rigorous code review, many agent skills are simple text files (SKILL.md) that instruct an LLM to perform arbitrary actions — including executing shell commands, accessing APIs, and modifying files.

The tool provides:

Automated vulnerability scanning for AI agent skill files
Pattern-based malicious behavior detection including command injection, data exfiltration, and privilege escalation
Framework-specific analysis for Claude Code, GitHub Copilot, Codex CLI, and more
Remediation guidance with specific fixes for detected vulnerabilities
CI/CD integration for pre-installation scanning in automated pipelines

Installation Guide #

Prerequisites #

Python: 3.12+ (required for async scanning features)
Operating System: Linux, macOS, or Windows WSL2
Disk Space: 500MB for scanner + skill databases
Network: Required for downloading skill databases and updates

Option 1: Pip Installation #

# Install SkillSpector from PyPI
pip install skillspector

# Verify installation
skillspector --version

# Download the latest skill database
skillspector update-db

Option 2: From Source #

# Clone the repository
git clone https://github.com/NVIDIA/SkillSpector.git
cd SkillSpector

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e .

# Initialize the scanner
skillspector init --download-database

Option 3: Docker Deployment #

# Pull the official image
docker pull nvcr.io/nvidia/skillspector:latest

# Run a scan
docker run --rm \
  -v ${PWD}/skills:/app/skills \
  nvcr.io/nvidia/skillspector:latest \
  scan /app/skills

# Schedule regular scans
docker run -d \
  --name skillspector \
  -v ${PWD}/skills:/app/skills \
  -v ${PWD}/reports:/app/reports \
  nvcr.io/nvidia/skillspector:latest \
  daemon --interval 3600

Scanning Capabilities #

Vulnerability Detection Categories #

SkillSpector detects vulnerabilities across multiple categories:

Category	Description	Severity
Command Injection	Skills that execute arbitrary shell commands	Critical
Data Exfiltration	Skills that send data to external endpoints	Critical
Privilege Escalation	Skills that attempt to gain elevated access	High
Credential Theft	Skills that access or transmit credentials	Critical
File Manipulation	Skills that read/write arbitrary files	Medium
Network Access	Skills that establish unexpected network connections	Medium
API Abuse	Skills that misuse API keys or tokens	High
Social Engineering	Skills that manipulate users into unsafe actions	Medium
Supply Chain	Skills that depend on unverified external packages	High
Information Disclosure	Skills that expose sensitive system information	Low

Basic Scanning #

# Scan a single skill file
skillspector scan my_skill.md

# Scan a directory of skills
skillspector scan ./skills/

# Scan with detailed output
skillspector scan ./skills/ --verbose

# Scan and generate a report
skillspector scan ./skills/ --output report.json --format json

Advanced Scanning Options #

# Scan with custom severity threshold
skillspector scan ./skills/ --min-severity high

# Scan with specific vulnerability categories
skillspector scan ./skills/ --categories command_injection,data_exfiltration

# Scan with framework-specific rules
skillspector scan ./skills/ --framework claude-code

# Scan with dependency resolution
skillspector scan ./skills/ --resolve-deps --follow-links

# Scan with remediation suggestions
skillspector scan ./skills/ --remediate --output fixes/

Python API Usage #

from skillspector.scanner import SkillScanner
from skillspector.report import ReportFormatter

# Initialize the scanner
scanner = SkillScanner(
    database_path="~/.skillspector/db",
    categories=["all"],
    severity_threshold="medium"
)

# Scan a skill file
result = scanner.scan("suspicious_skill.md")

# Analyze the results
print(f"Vulnerabilities found: {result.vulnerability_count}")
print(f"Severity: {result.overall_severity}")

# Get detailed findings
for finding in result.findings:
    print(f"- [{finding.severity}] {finding.category}: {finding.description}")
    print(f"  Location: {finding.location}")
    print(f"  Remediation: {finding.remediation}")

# Generate a formatted report
formatter = ReportFormatter(format="markdown")
report = formatter.generate(result)
print(report)

Framework-Specific Analysis #

Claude Code Skills #

Claude Code skills are Markdown files (SKILL.md) that define behavioral instructions for the Claude Code agent. SkillSpector analyzes these files for:

Dangerous shell command patterns in instructions
API key exposure in skill content
File system access beyond intended scope
Network connection requests

# Scan Claude Code skills
skillspector scan ~/.claude/skills/ --framework claude-code

# Check for dangerous command patterns
skillspector check-commands ~/.claude/skills/ --framework claude-code

GitHub Copilot Skills #

Copilot skills define custom behaviors for the Copilot agent. SkillSpector detects:

Unauthorized code repository access patterns
API endpoint manipulation
Credential harvesting in skill definitions
Data exfiltration through Copilot’s built-in tools

# Scan Copilot skills
skillspector scan ~/.config/github-copilot/skills/ --framework copilot

# Check for repository access patterns
skillspector check-repo-access ~/.config/github-copilot/skills/

Codex CLI Skills #

Codex CLI skills extend the Codex agent’s capabilities. SkillSpector looks for:

Arbitrary command execution instructions
File system traversal beyond project scope
Network communication with unknown endpoints
Environment variable manipulation

# Scan Codex skills
skillspector scan ~/.codex/skills/ --framework codex

# Check for environment manipulation
skillspector check-env-manipulation ~/.codex/skills/

Gemini CLI Skills #

Gemini CLI skills provide custom instructions for Google’s Gemini CLI agent. SkillSpector analyzes:

Tool usage patterns that could bypass safety measures
Prompt injection vectors in skill definitions
Data access scope violations
External API call patterns

# Scan Gemini CLI skills
skillspector scan ~/.gemini/skills/ --framework gemini

# Check for prompt injection vectors
skillspector check-injection ~/.gemini/skills/

CI/CD Integration #

GitHub Actions Integration #

# .github/workflows/skill-security.yml
name: Skill Security Scan
on:
  pull_request:
    paths:
      - 'skills/**'
      - '**/SKILL.md'

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install SkillSpector
        run: pip install skillspector

      - name: Update vulnerability database
        run: skillspector update-db

      - name: Scan skills
        run: |
          skillspector scan ./skills/ \
            --min-severity high \
            --output skillspector-report.json \
            --format json

      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: skillspector-report
          path: skillspector-report.json

GitLab CI Integration #

# .gitlab-ci.yml
skill-security-scan:
  image: python:3.12
  script:
    - pip install skillspector
    - skillspector update-db
    - skillspector scan ./skills/ --output gl-skillspector-report.json --format json
  artifacts:
    reports:
      sast: gl-skillspector-report.json

Pre-Installation Hook #

#!/bin/bash
# .git/hooks/pre-install-skill

# Run SkillSpector before installing any new skill
skillspector scan "$1" --min-severity critical
if [ $? -ne 0 ]; then
  echo "ERROR: Skill contains critical vulnerabilities. Installation blocked."
  exit 1
fi

echo "Skill passed security scan. Proceeding with installation."
exit 0

Remediation Guidance #

Automatic Fix Suggestions #

SkillSpector provides specific remediation steps for each detected vulnerability:

# Generate fix suggestions
skillspector scan ./skills/ --remediate --output-dir ./remediated/

# View remediation details
skillspector remediation ./skills/suspicious.md

Example remediation output:

Finding: Command Injection in shell commands
Severity: CRITICAL
Location: Line 45: "Execute: rm -rf /tmp/* && curl..."

Remediation:
  1. Remove unrestricted shell command patterns
  2. Replace with specific, bounded commands
  3. Add input validation for any user-provided parameters
  
  Before: rm -rf /tmp/* && curl $EXTERNAL_URL
  After:  find /tmp -name "*.log" -mtime +7 -delete
          curl --max-time 30 --connect-timeout 10 "$SANITIZED_URL"

  4. Add allowlist for permitted external domains
  5. Implement rate limiting for external requests

Security Best Practices for Skill Authors #

Minimize shell command scope: Only include commands necessary for the skill’s purpose
Validate all inputs: Never pass user input directly to shell commands
Avoid credential handling: Do not include API keys, passwords, or tokens in skill files
Limit file system access: Restrict file operations to project directories only
Document data flows: Clearly describe what data the skill accesses and where it sends it
Use allowlists: Specify allowed domains, file patterns, and command parameters
Review dependencies: Audit any external packages the skill requires

Comparison: SkillSpector vs Traditional Security Tools #

Feature	SkillSpector	Bandit	Snyk	Trivy
AI Agent Skills	Yes	No	No	No
SKILL.md Analysis	Yes	No	No	No
Framework Support	4+ frameworks	Python only	Multiple	Containers/files
Prompt Injection	Yes	No	Partial	No
Command Injection	Yes	Yes	Yes	No
Data Exfiltration	Yes	No	Yes	No
CI/CD Ready	Yes	Yes	Yes	Yes
Price	Free	Free	Freemium	Free (OSS)

Limitations #

Pattern-based detection: Some sophisticated attacks may evade pattern matching
Semantic understanding: The scanner analyzes skill text but cannot fully understand LLM behavioral implications
Framework evolution: New agent frameworks require updated rule sets
False positives: Legitimate skills may trigger warnings that require manual review
Database currency: Detection effectiveness depends on regular database updates

Getting Started Checklist #

# 1. Install SkillSpector
pip install skillspector

# 2. Update the vulnerability database
skillspector update-db

# 3. Scan existing skills
skillspector scan ~/.claude/skills/ --framework claude-code

# 4. Set up CI/CD integration
# Add the GitHub Actions workflow from the documentation

# 5. Configure pre-installation hooks
# Copy the pre-install hook to your git hooks directory

# 6. Schedule regular scans
crontab -e
# Add: 0 */6 * * * skillspector scan ~/.claude/skills/ --output daily-report.json

Conclusion #

SkillSpector fills a critical gap in the AI agent security landscape. As agent skills become a standard extension mechanism for AI coding assistants, the need for dedicated security scanning becomes paramount. By providing automated vulnerability detection, framework-specific analysis, and CI/CD integration, SkillSpector helps developers maintain secure agent ecosystems.

Developed by NVIDIA and backed by the cybersecurity research community, SkillSpector represents the first dedicated security tool for the emerging AI agent skills ecosystem. Its open-source nature ensures transparency and community-driven improvement, making it an essential tool for anyone deploying AI agent skills in production.

Sources #

CTA #

Protect your AI agent ecosystem today. Visit the SkillSpector GitHub repository to get started. For hosting your security scanning infrastructure, consider HTStack for affordable CI/CD runners, or DigitalOcean for managed GitHub Actions runners.

For enterprise security scanning at scale, ProxyShard offers secure proxy infrastructure for isolating agent skill execution environments.

FAQ #

q: How often should the vulnerability database be updated? #

a: NVIDIA recommends updating the database weekly, ideally before each scan. SkillSpector includes an automatic update check that notifies you when new signatures are available. For CI/CD pipelines, configure the database update as part of the scan step.

q: Does SkillSpector work with custom or proprietary agent frameworks? #

a: SkillSpector’s scanning engine is framework-agnostic. While it includes pre-configured rules for Claude Code, Copilot, Codex CLI, and Gemini CLI, you can define custom rule sets for any agent framework by creating a rules file in the supported format.

q: Can SkillSpector detect supply chain attacks in agent skills? #

a: Yes. SkillSpector analyzes skill dependencies, external package references, and network communication patterns to detect potential supply chain attacks. It flags skills that depend on unverified packages or establish connections to unknown endpoints.

q: What is the expected scan time for a directory of skills? #

a: For a typical directory of 100 skill files, SkillSpector completes a full scan in under 10 seconds. Larger directories (1000+ files) may take 30-60 seconds. The scan time scales linearly with the number of files, not their content size.

q: Does SkillSpector support team collaboration features? #

a: Currently, SkillSpector focuses on individual scanning and reporting. Team features like shared vulnerability databases and collaborative remediation are planned for future releases. The JSON report format is designed for easy integration with team collaboration platforms.

q: How does SkillSpector handle false positives? #

a: SkillSpector assigns confidence scores to each finding and allows filtering by severity threshold. False positives can be suppressed by adding exclusion patterns to your configuration. NVIDIA actively reviews and improves detection accuracy based on community feedback.