安全与治理 · security · 验证于 2026-08-28 ✓ 实测验证

skillspector

已验证 2026-08-28安装前漏洞/恶意模式扫描实测通过；NVIDIA 出品的 AI agent 技能安全扫描器。

AI agent 技能安全扫描器：安装前检测漏洞、恶意模式与安全配置（NVIDIA 出品）

详细版 → 所属问题域：安全与治理 遇到问题？去问题空间 →

你会遇到什么

这个工具解决什么问题：装技能前先安检。SkillSpector（NVIDIA 出品）扫描技能（SKILL.md/目录/仓库）找漏洞、恶意模式与不安全配置——装 agent-skills、superpowers 这类技能包之前，先扫一遍再启用。 什么时候用：

  • 你要从网上下载技能装进 Agent（装前扫描，装后安心）；
  • 你要静态扫描（免 API key，--no-llm）；
  • 你要把扫描作为 MCP server 接入 Agent 流程（官方形态）。

什么时候别用：只信任自己的技能、不装外部技能时——扫描器本身是只读的，装上备用即可。 和相邻工具的边界：与 agentshield（Claude Code 配置审计）互补——它扫技能内容，agentshield 扫 Agent 配置；两者都只读、无后台进程。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：pip 包 skillspector（或 release wheel）。skillspector scan <目标> --no-llm 静态扫描（免 key），输出 SkillSpector Security Report（Score/Severity/Components/Issues 清单，含 SC2 外部脚本拉取、TM2 工具链滥用等检出）；不带 --no-llm 时尝试 LLM 语义分析（需 OPENAI_API_KEY 或 SKILLSPECTOR_PROVIDER，无 key 自动跳过并警告）。支持扫描目录/文件、Git 仓库/URL/zip（官方支持，未实测）；skillspector mcp 起 MCP server（官方形态，未实测）。 关键概念：

  • --no-llm：静态模式（免 API key）；
  • Report：Score/Severity/Components/Issues 结构化报告；
  • mcp：MCP server 形态（供 agent 工具调用）。

装完它动哪里：零写面（只读扫描器，无后台进程）。

快速修复（不想看讲解，直接跑）

note: 本环境实测路径：skillspector 不在 PyPI（证据，官方源与清华镜像均 404），发行渠道 = GitHub Release wheel——wheel 下载走 gh-proxy 加速、pip 依赖走清华镜像
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

预期输出: 2.10.0（无 --version 标志时以 --help 为准）

一步步来

第 1 步：装（为什么锁版本：2.10.0 为收录实测版本）

讲解：skillspector 不在 PyPI，发行渠道是 GitHub Release wheel——先下载 wheel（国内 gh-proxy 加速），pip 只负责装 wheel 与依赖（依赖走清华镜像）。装完验证版本（2.10.0；若包无 --version 标志以 --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

预期输出: 2.10.0（无 --version 标志时以 --help 为准）

装好确认：

  • 版本输出或 --help 正常。

卡住怎么办：

  • wheel 下载慢 → 换 gh-proxy 镜像（gh-proxy.com / gh-proxy.llyke.com 竞速，2026-08-28 实测后者更快）；pip 依赖慢 → 确认带清华镜像前缀；
  • 命令找不到 → venv 场景先激活 venv。

第 2 步：静态扫描第一个技能目录（本环境实测，免 API key）

讲解：--no-llm 是静态模式，不需要任何 key。扫你的技能目录（如 ./skills/my-skill），输出安全报告。

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

预期输出: SkillSpector Security Report（Score/Severity/Components/Issues 清单，含 SC2 外部脚本拉取、TM2 工具链滥用等检出）

装好确认：

  • 报告有 Score/Severity/Issues；
  • 无 key 也不报错（--no-llm 模式）。

卡住怎么办：

  • 报缺 key → 确认用了 --no-llm（不带它会尝试 LLM 分析，无 key 自动跳过并警告，不算错误）。

第 3 步：带 LLM 语义分析 / 扫远端 / MCP（按需）

讲解：不带 --no-llm 时做静态 + 语义分析（需 OPENAI_API_KEY 或 SKILLSPECTOR_PROVIDER）；扫 Git 仓库/URL/zip 官方支持（未实测）；MCP server 形态（未实测）。

skillspector scan ./skills/my-skill

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

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

预期输出: 同报告格式（Source 显示远端地址）

skillspector mcp

预期输出: MCP server 启动（供 agent 工具调用）

卡住怎么办：

  • 远端仓库不可达 → 确认网络与仓库地址（官方支持形态，未实测）；
  • MCP 起不来 → 以官方文档为准（本环境未实测）。

怎么确认修好了

第 1 步：确认安装与静态扫描（免 key）

讲解：skillspector --version 确认版本；--no-llm 静态扫描跑出带 Score/Severity/Issues 的报告，说明核心链路通，且不需要任何 API key。

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

预期输出: 2.10.0；SkillSpector Security Report（Score/Severity/Components/Issues 清单）

卡住怎么办：

  • 报缺 key → 确认用了 --no-llm（不带它会尝试 LLM 分析，无 key 自动跳过并警告，不算错误）；
  • 命令找不到 → venv 场景先激活 venv。

第 2 步：确认 LLM 分析 / MCP 形态（按需）

讲解：不带 --no-llm 能跑出 semantic 分析器说明 LLM 链路可用（需 key）；skillspector mcp 能启动说明 MCP server 形态就位（本环境未实测）。

skillspector scan ./skills/my-skill

预期输出: 静态 + 语义分析报告（semantic_developer_intent/quality_policy/security_discovery；无 key 时自动跳过并警告）

卡住怎么办：

  • 无 key 时语义段缺失 → 属预期行为（自动跳过并警告），配 OPENAI_API_KEY 或 SKILLSPECTOR_PROVIDER 后重跑；
  • MCP 起不来 → 以官方文档为准（本环境未实测）。

其它环境的表现（常见变体）

  • Python 版本：>= 3.10；wheel 任意 Python 3 版本可用（收录实测）。
  • 只读工具：零写面、无后台进程——扫技能目录、Agent 配置都是只读，不产生残留。
  • LLM 分析：可选；无 key 用 --no-llm 静态模式即可覆盖日常安全检查。
  • 共装：与 agentshield 互补不冲突（扫技能内容 vs 扫 Agent 配置，都只读）。

日常使用

启动与入口

CLI 按需调用；无常驻服务。

常用操作

操作一：静态扫描技能目录（本环境实测；免 API key）

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

预期输出: SkillSpector Security Report（Score/Severity/Components/Issues 清单，含 SC2 外部脚本拉取、TM2 工具链滥用等检出）

操作二：带 LLM 语义分析（可选；需 OPENAI_API_KEY 或 SKILLSPECTOR_PROVIDER）

skillspector scan ./skills/my-skill

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

操作三：扫描 Git 仓库/URL/zip（官方支持，未实测）

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

预期输出: 同报告格式（Source 显示远端地址）

操作四：作为 MCP 服务器接入（官方形态，未实测）

skillspector mcp

预期输出: MCP server 启动（供 agent 工具调用）

数据与目录

  • 零写面：不写配置、无缓存目录（只读扫描器）。

卸载与清理

note: pip 包自动卸载（幂等）；零写面
pip uninstall -y skillspector 2>/dev/null || true
command -v skillspector >/dev/null 2>&1 && echo '残留: skillspector 仍存在' || echo 'skillspector removed: OK'

预期输出: skillspector removed: OK

依赖警告

  • 版本：[2.10.0, 2.10.0] 锁定（收录实测版本）。
  • 环境：Python >= 3.10；wheel 任意 Python 3 版本可用（收录实测）。
  • 网络：不在 PyPI——wheel 从 GitHub Release 下载（国内走 gh-proxy，2026-08-28 实测 gh-proxy.llyke.com 更快）；pip 依赖用清华镜像（国内建议）。
  • 写面：零（只读扫描器，无后台进程）。
  • LLM 分析：可选，需 OPENAI_API_KEY 或 SKILLSPECTOR_PROVIDER；无 key 用 --no-llm 静态模式。
  • 共装：与 agentshield 互补不冲突（扫技能内容 vs 扫 Agent 配置，都只读）。

FAQ（常见问题）

  • 问：没有 API key 能用吗？答：能。--no-llm 静态模式免 key（本环境实测）；不带 --no-llm 时无 key 会自动跳过 LLM 分析并警告。
  • 问：扫描会改我的文件吗？答：不会。只读扫描器，零写面，无后台进程。
  • 问：和 agentshield 重复吗？答：不重复——它扫技能内容（SC2/TM2 等检出），agentshield 扫 Claude Code 配置（密钥/权限/hooks/MCP）；建议装技能后两个都跑。
  • 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。
验证证据
  • 实测：实测记录（本地留存）（2026-08-28，pip 安装 + version/help + 静态扫描冒烟）。
  • 未实测：LLM 语义分析（无 key）；远端仓库扫描与 MCP 形态（命令来自官方文档）。

引用：skillspector · 验证于 2026-08-28 · v2.10.0~2.10.0

相关问题（问题域）

出问题了？排障方案

排障手册：skillspector（L34 批次 1）

症状 → 原因 → 解法 → 验证证据 四段结构。
素材来源：L33 分源记录（CSDN/知乎/B站）+ 国外信号（L32：Issue #199）+ 本市场实测（2026-08-28 隔离 venv 安装/卸载闭环 + PyPI 排查）。
采集纪律：零账号匿名检索；不破解反爬；未碰 GitHub。check-words HARD 0。

基本信息

  • 条目名称：skillspector（NVIDIA/SkillSpector，Apache-2.0，v2.10.0 收录）
  • L33 分源信号：CSDN=3 / 掘金=0 / 知乎=3 / B站=1（中）
  • §14 角色：core；分类：security
  • 定位：AI agent 技能安全扫描器——安装前检测漏洞、恶意模式与安全配置（NVIDIA 开源）
  • 本市场安装路径：GitHub Release wheel 直装（pip 依赖走清华镜像）
  • 主要安装形态：pip（wheel）/ MCP server 模式 / CLI（scan/mcp/baseline）

症状 → 原因 → 解法 → 验证证据

1. pip install skillspector 找不到包（No matching distribution）

症状

pip install skillspector==2.10.0 报：

# 来源: Trove 排障手册 · 验证于 2026-08-28
ERROR: Could not find a version that satisfies the requirement skillspector==2.10.0 (from versions: none)
ERROR: No matching distribution found for skillspector==2.10.0

原因

skillspector 不在 PyPI 上——发行渠道 = GitHub Release（wheel + sdist 资产）。按 PyPI 方式安装必然失败；这是国内教程最常见的坑（部分教程写 pip install git+... 也是绕行做法）。

解法

  1. 正确姿势（本市场实测）：下载 release wheel 后 pip 安装：
# 来源: Trove 排障手册 · 验证于 2026-08-28
   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
  1. 注意 wheel 文件名必须保持原样（pip 校验文件名格式，改短会报 Invalid wheel filename）。
  2. 也可 pip install git+https://github.com/NVIDIA/SkillSpector.git（源码方式，国内直连不稳）。

验证证据

  • 本市场实测 2026-08-28（实测记录（本地留存））：PyPI JSON API → {"message": "Not Found"}；清华镜像 simple → 404；pip index versions → No matching distribution。三路复核确认 PyPI 无此包。
  • 闭环 v3：wheel 下载 468K → pip 安装全部依赖成功 → SkillSpector v2.10.0 → install exit=0。

2. Failed building wheel for yara-python（构建依赖缺失）

症状

pip 安装时报 Failed building wheel for yara-python / error: command 'gcc' failed。

原因

yara-python 对新版 Python（3.13/3.14）没有预编译 wheel，会从源码构建；系统缺 build 工具链（gcc/make/python3-dev）时构建失败。

解法

  1. 装构建依赖：sudo apt install build-essential python3-dev。
  2. 用系统 Python 官方版本的预编译 wheel（如 cp312 多数平台有轮子，构建场景少）。
  3. 构建再次失败时看完整日志末尾的真实编译错误（缺头文件/库按名补装）。

验证证据

  • 网页案例：CSDN 文库（Failed building wheel → build-essential python3-dev，2026-07）。
  • 本市场实测：Python 3.14 下 yara-python 4.5.4 无 cp314 wheel，真实走了源码构建路径并成功（闭环 v3：Building wheel for yara-python ... Successfully built）——证明构建路径存在且本环境工具链齐全；缺工具链的机器会在此步失败。

3. MCP 模式 stdio 挂起（可选依赖缺失）

症状

用 MCP server 模式（skillspector mcp）时进程挂起无输出。

原因

MCP 模式依赖可选组件，默认 pip 安装不完整（Issue #199 场景）；stdio 挂起时无报错，像死机。

解法

  1. 先 Ctrl+C 退出，确认依赖：按项目文档安装 MCP 相关可选依赖后重启。
  2. 排查期间用 skillspector scan 主路径（不需要 MCP 也能完成扫描）。
  3. 挂起时检查：skillspector mcp --help 是否正常输出（能输出说明 CLI 层正常，问题在会话协议侧）。

验证证据

  • 国外信号：Issue #199（mcp stdio 挂起，可选 mcp 依赖缺失导致安装不完整）。
  • 本市场实测：mcp 模式未实跑（指南标注）；scan 主路径可用（构造样本检出）。

4. 依赖版本冲突警告

症状

安装或运行时提示与已装包版本冲突（langchain/openai/pydantic 等）。

原因

skillspector 依赖较新的 langchain/openai/langgraph 家族；与系统里其它项目的旧版本互相覆盖。

解法

  1. 隔离安装：python3 -m venv <dir> 后装进 venv（本市场实测方式），不污染系统 Python。
  2. 或按提示升级对应包；升级前备份项目锁文件（requirements/uv.lock 等）。
  3. 冲突严重时用 pipx/uv 管理独立环境。

验证证据

  • 网页案例：CSDN 文库（依赖版本冲突，2026-07）。
  • 本市场实测：隔离 venv 安装 60+ 依赖无冲突（闭环 v3：Successfully installed ... skillspector-2.10.0）；系统 Python 未受影响。

5. 风险评分 >50 输出 DO NOT INSTALL

症状

扫描结果出现 DO NOT INSTALL 或高风险分数，用户以为工具坏了。

原因

这是评分逻辑不是故障：风险评分 >50 → DO NOT INSTALL；中低分 → CAUTION/建议（CSDN 源码解析确认的分级逻辑）。扫描器检出的问题条目（SC2 外部脚本拉取、TM 链滥用等）才是判断依据。

解法

  1. 看报告 Issues 列表的 Severity/Confidence，判断是否真的不能装。
  2. 分数受评分器影响，同一技能不同版本分数可能不同；结合 baseline 抑制已知项。
  3. 拿不准时人工检查 SKILL.md 中检出行（报告给出行号）。

验证证据

  • 网页案例：CSDN（风险评分>50 DO NOT INSTALL，2026-06；源码解析）。
  • 本市场实测：构造样本（SKILL.md 含 curl|bash + token 泄漏）→ Score 40/100 MEDIUM + 2 个 HIGH 检出（SC2 90% / TM2 70%），报告结构完整。

6. semantic_* 分析器警告（缺 API key）

症状

skillspector --version / scan 输出：

# 来源: Trove 排障手册 · 验证于 2026-08-28
WARNING [skillspector.graph] Skipping analyzer semantic_developer_intent: required API key is missing

原因

LLM 语义分析器需要 OPENAI_API_KEY（或 SKILLSPECTOR_PROVIDER 配置）；没 key 时自动跳过——不是错误。

解法

  1. 不配 key：静态扫描完全可用（--no-llm），规则检测（YARA/模式）不依赖 LLM。
  2. 要语义分析：配 OPENAI_API_KEY 环境变量或按文档设 SKILLSPECTOR_PROVIDER。
  3. 警告可安全忽略，不影响退出码与报告生成。

验证证据

  • 本市场实测：安装与运行均输出 3 条 semantic 跳过警告，exit 0，扫描正常（+ 闭环 v3）。

本市场实测安装 / 卸载（2026-08-28）

安装（manifest install.cmd，隔离 venv /tmp/l34-sp/venv，Python 3.14.4）：

# 来源: Trove 排障手册 · 验证于 2026-08-28
[install] curl -sL wheel（gh-proxy，468K）→ pip install -i 清华镜像 skillspector-2.10.0-py3-none-any.whl
依赖：boto3/httpx/langchain-*/langgraph/openai/pydantic/yara-python（源码构建成功）等 60+ 包
SkillSpector v2.10.0（3 条 semantic 跳过警告，exit 0）
[install] exit=0

卸载（manifest uninstall.cmd + 修正后的 verify）：

# 来源: Trove 排障手册 · 验证于 2026-08-28
[uninstall] pip uninstall -y skillspector → Successfully uninstalled skillspector-2.10.0
[uninstall] 验证: skillspector removed: OK（fresh shell，verify exit=0）
  • 完整日志：实测记录（本地留存）。
  • PyPI 缺失排查：实测记录（本地留存）。
  • 扫描冒烟：实测记录（本地留存）（构造样本检出 2 个 HIGH，只读扫描确认）。
  • 未能实测：MCP server 模式实跑、LLM 语义分析（无 API key）、baseline 命令。

冲突标注

  • possible-compatible（推断态）：全部收录条目——skillspector 只读扫描（扫描前后目录零新增）、无 daemon、无配置写面、无端口；CLI 面与任何条目共存无共享写面（矩阵对子）。
  • 备注：LLM 语义分析如需与其它工具共用 API key 环境变量，属配置面注意项（非写面冲突）。

名称混淆

  • 大小写：项目名 SkillSpector（NVIDIA 开源），命令 skillspector。
  • 渠道：PyPI 上无此包（见症状 1），检索/安装认准 GitHub 仓库 NVIDIA/SkillSpector 与 release 资产。
  • 与其它技能安全/检查类工具区分（如 agent-skills 等技能包，功能不同）。

判据（验证状态）

  • 症状清单：
  • [x] pip install 找不到包 → 发行渠道 = GitHub Release wheel（本市场三路复核 + 闭环实测）
  • [x] Failed building wheel for yara-python → build-essential python3-dev（CSDN 文库 2026-07；本市场源码构建路径实测）
  • [x] 可选 mcp 依赖缺失导致 stdio 挂起（Issue #199）
  • [x] 依赖版本冲突警告（CSDN 文库 2026-07；venv 隔离解法实测）
  • [x] 风险评分>50 输出 DO NOT INSTALL（CSDN 2026-06；评分逻辑说明）
  • [x] semantic_* 分析器缺 key 警告（本市场实测）
  • 实测步骤：
  • [x] 安装验证（manifest install.cmd 修正后：wheel 直装 + 依赖走镜像 → SkillSpector v2.10.0 exit 0）
  • [x] 卸载验证（manifest uninstall.cmd：pip uninstall → verify 零残留 exit 0）
  • [x] 网络/镜像场景（gh-proxy wheel 下载 + 清华镜像依赖；）
  • [x] 未能实测项：MCP 模式实跑、LLM 语义分析（无 key）、baseline

验收

  • [x] 症状 → 原因 → 解法 → 验证证据 四段齐全（6 症状）
  • [x] 名称混淆已点名（大小写；PyPI 无包；渠道认准 GitHub）
  • [x] check-words HARD 0
  • [x] validate 通过
  • [x] 未碰 GitHub / 未用任何账号

所属组合包 （1）

矩阵暂无该工具对子。

← 返回工具货架 ｜ 遇到其它问题？去 问题空间 提交求助卡 ｜ 预检与证据记录由维护流程本地留存，仅公开结论与来源