skillspector

What you will run into

What this tool solves: a security check before installing skills. SkillSpector (by NVIDIA) scans skills (SKILL.md/directories/repos) for vulnerabilities, malicious patterns and unsafe configurations — before enabling a skill package like agent-skills or superpowers, scan it first. When to use it:

• You download skills from the internet to install into your Agent (scan before install, peace of mind after);
• You want a static scan (no API key, --no-llm);
• You want to wire the scanner into your Agent flow as an MCP server (official form).

When not to use it: you only trust your own skills and never install external ones — the scanner itself is read-only, just install it and keep it around. Boundary with neighboring tools: complementary to agentshield (Claude Code config audit) — it scans skill content, agentshield scans Agent config; both are read-only with no background process.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

How it works: pip package skillspector (or release wheel). skillspector scan <target> --no-llm does a static scan (no key) and outputs a SkillSpector Security Report (Score/Severity/Components/Issues list, including detections like SC2 external script fetching, TM2 toolchain abuse); without --no-llm it tries LLM semantic analysis (needs OPENAI_API_KEY or SKILLSPECTOR_PROVIDER, skips with a warning when no key). Supports scanning directories/files, Git repos/URLs/zips (officially supported, not tested); skillspector mcp starts an MCP server (official form, not tested). Key concepts:

• --no-llm: static mode (no API key);
• Report: structured report with Score/Severity/Components/Issues;
• mcp: MCP server form (for agent tool calls).

Where it writes: zero write surface (read-only scanner, no background process).

Step by step

Step 1: Install (why the version is locked: 2.10.0 is the verified collection version)

Why: skillspector is not on PyPI; the distribution channel is the GitHub Release wheel — download the wheel first (gh-proxy on mainland), pip only installs the wheel and its dependencies (deps via the Tsinghua mirror). After install verify the version (2.10.0; if the package has no --version flag, go by --help).

curl -sL -o skillspector-2.10.0-py3-none-any.whl https://gh-proxy.com/https://github.com/NVIDIA/SkillSpector/releases/download/v2.10.0/skillspector-2.10.0-py3-none-any.whl && pip install -i https://pypi.tuna.tsinghua.edu.cn/simple skillspector-2.10.0-py3-none-any.whl
skillspector --version

Expected output: 2.10.0（无 --version 标志时以 --help 为准） After install, confirm:

• version output or --help works.

Stuck? How to recover:

• wheel download slow → switch gh-proxy mirrors (gh-proxy.com / gh-proxy.llyke.com race, the latter measured faster 2026-08-28); pip deps slow → confirm the Tsinghua mirror prefix;
• command not found → activate the venv first in venv setups.

Step 2: Statically scan your first skill directory (verified in this environment, no API key)

Why: --no-llm is static mode and needs no key. Scan your skill directory (e.g. ./skills/my-skill) and get the security report.

skillspector scan ./skills/my-skill --no-llm

Expected output: SkillSpector Security Report（Score/Severity/Components/Issues 清单，含 SC2 外部脚本拉取、TM2 工具链滥用等检出） After install, confirm:

• the report has Score/Severity/Issues;
• no error without a key (--no-llm mode).

Stuck? How to recover:

• missing key error → confirm you used --no-llm (without it, it tries LLM analysis; no key auto-skips with a warning, which is not an error).

Step 3: LLM semantic analysis / remote scan / MCP (as needed)

Why: without --no-llm it runs static + semantic analysis (needs OPENAI_API_KEY or SKILLSPECTOR_PROVIDER); scanning Git repos/URLs/zips is officially supported (not tested); MCP server form (not tested).

skillspector scan ./skills/my-skill

Expected output: 静态 + 语义分析报告（semantic_developer_intent/quality_policy/security_discovery 分析器；无 key 时自动跳过并警告）

skillspector scan https://github.com/owner/repo

Expected output: 同报告格式（Source 显示远端地址）

skillspector mcp

Expected output: MCP server 启动（供 agent 工具调用） Stuck? How to recover:

• remote repo unreachable → confirm the network and repo URL (officially supported form, not tested);
• MCP won't start → follow the official docs (not tested in this environment).

How to confirm it works

Step 1: Confirm install and static scan (no key)

Why: skillspector --version confirms the version; a --no-llm static scan producing a report with Score/Severity/Issues means the core path works and needs no API key.

skillspector --version
skillspector scan ./skills/my-skill --no-llm

Expected output: 2.10.0；SkillSpector Security Report（Score/Severity/Components/Issues 清单） Stuck? How to recover:

• missing key error → confirm you used --no-llm (without it, it tries LLM analysis; no key auto-skips with a warning, not an error);
• command not found → activate the venv first in venv setups.

Step 2: Confirm LLM analysis / MCP form (as needed)

Why: running without --no-llm and getting the semantic analyzers means the LLM path works (needs a key); skillspector mcp starting means the MCP server form is in place (not tested in this environment).

skillspector scan ./skills/my-skill

Expected output: 静态 + 语义分析报告（semantic_developer_intent/quality_policy/security_discovery；无 key 时自动跳过并警告） Stuck? How to recover:

• semantic section missing without a key → expected behavior (auto-skip with warning); rerun with OPENAI_API_KEY or SKILLSPECTOR_PROVIDER;
• MCP won't start → follow the official docs (not tested in this environment).

Other environments

• Python version: >= 3.10; the wheel works on any Python 3 version (verified in collection).
• Read-only tool: zero write surface, no background process — scanning skill directories or Agent config is read-only, no residue.
• LLM analysis: optional; without a key, --no-llm static mode covers everyday security checks.
• Co-install: complementary to agentshield, no conflict (scans skill content vs Agent config, both read-only).

Daily usage

Startup and entry

CLI on demand; no resident service.

Common operations

Operation 1: Statically scan a skill directory (verified in this environment; no API key)

skillspector scan ./skills/my-skill --no-llm

Expected output: SkillSpector Security Report（Score/Severity/Components/Issues 清单，含 SC2 外部脚本拉取、TM2 工具链滥用等检出） Operation 2: LLM semantic analysis (optional; needs OPENAI_API_KEY or SKILLSPECTOR_PROVIDER)

skillspector scan ./skills/my-skill

Expected output: 静态 + 语义分析报告（semantic_developer_intent/quality_policy/security_discovery 分析器；无 key 时自动跳过并警告） Operation 3: Scan a Git repo/URL/zip (officially supported, not tested)

skillspector scan https://github.com/owner/repo

Expected output: 同报告格式（Source 显示远端地址） Operation 4: Wire in as an MCP server (official form, not tested)

skillspector mcp

Expected output: MCP server 启动（供 agent 工具调用）

Data and directories

• Zero write surface: no config, no cache directory (read-only scanner).

Uninstall & cleanup

note: pip package auto-uninstall (idempotent); zero write surface

pip uninstall -y skillspector 2>/dev/null || true
command -v skillspector >/dev/null 2>&1 && echo '残留: skillspector 仍存在' || echo 'skillspector removed: OK'

Expected output: skillspector removed: OK

Dependency warnings

• Version: [2.10.0, 2.10.0] locked (verified collection version).
• Environment: Python >= 3.10; the wheel works on any Python 3 version (verified in collection).
• Network: NOT on PyPI — wheel is downloaded from the GitHub Release (gh-proxy on mainland, gh-proxy.llyke.com measured faster 2026-08-28); pip deps via the Tsinghua mirror (recommended on mainland).
• Write surface: zero (read-only scanner, no background process).
• LLM analysis: optional, needs OPENAI_API_KEY or SKILLSPECTOR_PROVIDER; without a key use --no-llm static mode.
• Co-install: complementary to agentshield, no conflict (scans skill content vs Agent config, both read-only).

FAQ

• Q: Can I use it without an API key? A: Yes. --no-llm static mode needs no key (verified in this environment); without --no-llm and no key, it auto-skips LLM analysis with a warning.
• Q: Will scanning modify my files? A: No. Read-only scanner, zero write surface, no background process.
• Q: Does it duplicate agentshield? A: No — it scans skill content (SC2/TM2 detections etc.), agentshield scans Claude Code config (secrets/permissions/hooks/MCP); after installing skills, run both.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel; project issues go to the author's repository.