name: skill-scanner description: > Scan skill files for malware using the VirusTotal API before they are installed. Use this skill AUTOMATICALLY whenever a new skill is created, uploaded, edited, added, installed, or otherwise introduced into the system — including skills generated by the skill-creator. Also trigger when the user explicitly asks to "scan a skill", "check a skill for malware", "virus scan", or "security check". Requires the VT_API_KEY environment variable. Supports a hybrid mode: if the BurtTheCoder/mcp-virustotal MCP server is connected, use its get_file_report tool for fast hash lookups before falling back to the script for unknown files.

Skill Scanner

Scan every file in a skill directory against VirusTotal before it is trusted.

When to Run

Run the scanner every time a skill is:

• Created (e.g. after package_skill.py)
• Uploaded by the user
• Edited or updated
• Downloaded or installed from any source

Do not skip the scan even if the skill was generated locally.

Workflow: Hybrid (MCP + Script Fallback)

Choose the path based on what is available in the current environment.

Path A — MCP Server Available (Claude Desktop / Claude Code)

If the mcp-virustotal MCP server is connected (the get_file_report tool is available):

1. For each file in the skill directory, compute its SHA-256 hash (use the script's hash helper or shasum -a 256).
2. Call the MCP tool get_file_report with hash: "<sha256>" for each file.
3. Interpret results:
   • If the report shows 0 malicious detections → file is clean.
   • If the report shows ≥1 malicious detection → stop, report to user.
   • If the file is not found in VT (no existing report) → fall back to Path B for that file only.

This path is faster and uses no upload quota for known files.

Path B — Script Fallback (all platforms, including web/iOS)

Use when the MCP server is not connected, or for files unknown to VT.

1. Ensure VT_API_KEY is set in the environment. If missing, ask the user for their VirusTotal API key and export it.
2. Run the scanner script:

export VT_API_KEY="<key>"
python3 /mnt/skills/user/skill-scanner/scripts/scan_skill.py <skill-directory>

3. Interpret the JSON output:
   • "passed": true → Skill is clean. Proceed with installation or use.
   • "passed": false → Stop immediately. Report the flagged files with their verdicts and detection stats. Do not install or use the skill.
   • "verdict": "pending" → Analysis timed out. Inform the user and suggest re-running later or increasing --wait.

Path C — Hybrid (recommended on Desktop/Code)

Combine both paths for best coverage:

1. Compute SHA-256 hashes for all files in the skill directory.
2. Batch-check hashes via MCP get_file_report.
3. For any file MCP reports as "not found", run the script with --files targeting only those unknown files:

python3 /mnt/skills/user/skill-scanner/scripts/scan_skill.py <file1> <file2> ...

4. Merge results. If any file is malicious from either source, block the skill.

Script Options

How It Works

The script (scripts/scan_skill.py):

• Recursively collects all files in the skill directory (or accepts individual file paths)
• Computes SHA-256 hashes and checks VT for existing reports (avoids redundant uploads)
• Uploads unknown files to VT for fresh analysis
• Polls for results up to the --wait timeout
• Returns a JSON report with per-file verdicts and an overall pass/fail

MCP Server Setup (Optional, for Desktop/Code)

Install the MCP server for hash-based lookups without uploading files:

npm install -g @burtthecoder/mcp-virustotal

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "virustotal": {
      "command": "mcp-virustotal",
      "env": {
        "VIRUSTOTAL_API_KEY": "your-key-here"
      }
    }
  }
}

The API key is stored securely in this config file — no need to paste it per session.

Rate Limits

Free VT API keys allow 4 requests per minute. For skills with many files, the scan may take several minutes. The MCP path is faster since hash lookups are lightweight. Consider --wait 180 for larger skills using the script path.

Handling Failures

• No API key and no MCP: Prompt the user to provide their VirusTotal API key or set up the MCP server.
• Upload errors: Report the specific file and error. Suggest the user check their API key or VT account status.
• Timeouts: Suggest re-running with a longer --wait or checking the VT website directly using the SHA-256 hash.
• Malicious detections: Show the user the file name, SHA-256, and detection stats. Do not proceed with the skill.