Skip to content
Cisco AI Defense logo
CiscoAI Security

Quick Start — Skill Scanner

Quick Start

Get scanning in under a minute.

1. Install

# Using uv (recommended)
uv pip install cisco-ai-skill-scanner

# As a standalone tool
uv tool install cisco-ai-skill-scanner   # or: pipx install cisco-ai-skill-scanner

# Using pip
pip install cisco-ai-skill-scanner

Check the version with skill-scanner --version. This guide assumes 2.2.0 or newer.

2. Configure the LLM Judge

The LLM judge (--use-llm) is what reads a skill for intent, and every recommended setup uses it. It needs a model and, for most providers, a key:

export SKILL_SCANNER_LLM_API_KEY="your_api_key"
export SKILL_SCANNER_LLM_MODEL="anthropic/claude-sonnet-5-5"   # the default

3. Scan a Skill

# First test: check the CLI works (rules only; add --use-llm for real use)
skill-scanner scan /path/to/skill

# A third-party skill: rules plus the LLM judge, blocking HIGH (highest F1)
skill-scanner scan /path/to/skill --use-llm --policy balanced --fail-on-severity high

# Your own skills: the low-noise preset with the judge
skill-scanner scan /path/to/skill --use-llm --policy low-noise --fail-on-severity high

# Add Python dataflow and known-vulnerable dependency checks
skill-scanner scan /path/to/skill --use-llm --use-behavioral --use-osv

# Scan every skill in a public GitHub repository
skill-scanner scan-repo owner/repo

Not sure which flags to use? Run the interactive wizard:

skill-scanner

The wizard walks you through selecting a scan target, analyzers, policy, and output format. It recommends the LLM judge and leaves the meta-analyzer off.

4. Review Results

Clean Scan

============================================================
Skill: simple-math
============================================================
Status: [OK] SAFE
Max Severity: SAFE
Total Findings: 0
Scan Duration: 0.12s

Findings Detected

============================================================
Skill: config-analyzer
============================================================
Status: [FAIL] ISSUES FOUND
Max Severity: CRITICAL
Total Findings: 11
Scan Duration: 0.37s

Findings Summary:
  CRITICAL: 3
      HIGH: 3
    MEDIUM: 4
       LOW: 1

Detected threats include data exfiltration (HTTP POST to external servers), sensitive file access (~/.aws/credentials), environment variable theft, command injection, and base64 encoding + network exfiltration patterns.

5. Scan Multiple Skills

# Scan all skills in a directory
skill-scanner scan-all /path/to/skills --format table

# Recursive scan with cross-skill analysis
skill-scanner scan-all /path/to/skills --recursive --check-overlap

# Detailed markdown report
skill-scanner scan-all /path/to/skills --format markdown --detailed --output report.md

# Add the optional ATR and PromptGuard rule packs
skill-scanner scan-all /path/to/skills --recursive --rule-packs atr promptguard

6. Choose an Output Format

# JSON for CI/CD pipelines
skill-scanner scan /path/to/skill --format json --output results.json

# SARIF for GitHub Code Scanning
skill-scanner scan /path/to/skill --format sarif --output results.sarif

# Interactive HTML report
skill-scanner scan /path/to/skill --use-llm --format html --output report.html

# Compact table for terminal
skill-scanner scan-all /path/to/skills --format table

# Generate JSON and SARIF without scanning twice
skill-scanner scan /path/to/skill --format json --format sarif \
  --output-json results.json --output-sarif results.sarif

7. Use Scan Policies

Five presets ship: balanced (the default), low-noise, quiet, strict and permissive.

# Your own skills: fewer harmless flags, same detections
skill-scanner scan /path/to/skill --use-llm --policy low-noise

# The lowest false-positive rate: the fewest flags, only with the judge
skill-scanner scan /path/to/skill --use-llm --policy quiet

# Start a custom policy from a preset
skill-scanner generate-policy --preset low-noise -o my_policy.yaml
skill-scanner scan /path/to/skill --use-llm --policy my_policy.yaml

Recommended Settings shows which preset to use for which job, with measured recall, false-positive rate and F1.

8. Integrate with CI/CD

Fail builds when threats are detected:

skill-scanner scan-all ./skills --recursive --use-llm --policy low-noise --fail-on-severity high \
  --format sarif --output results.sarif

Or use the reusable GitHub Actions workflow:

name: Scan Skills
on:
  pull_request:
    paths: [".cursor/skills/**"]
jobs:
  scan:
    uses: cisco-ai-defense/skill-scanner/.github/workflows/scan-skills.yml@2.2.1
    with:
      scanner_version: "2.2.1"
      skill_path: .cursor/skills
      policy: low-noise
      fail_on_severity: high
      use_llm: true
      llm_model: anthropic/claude-sonnet-5-5
    secrets:
      llm_api_key: ${{ secrets.SKILL_SCANNER_LLM_API_KEY }}
    permissions:
      security-events: write
      contents: read
      actions: read

See GitHub Actions for the full CI/CD guide.

Useful Commands

# List available analyzers
skill-scanner list-analyzers

# Validate rule signatures
skill-scanner validate-rules

# Interactive policy configurator
skill-scanner configure-policy

# List bundled rule packs
skill-scanner scan /path/to/skill --rule-packs list

# Get help
skill-scanner --help
skill-scanner scan --help

Troubleshooting

uv not found

curl -LsSf https://astral.sh/uv/install.sh | sh

Module not found errors

uv sync --all-extras

Permission errors

uv manages its own virtual environment — no manual venv activation needed.

Next Steps