Skill安全扫描（免费版）

概述

AI Agent 生态中，第三方 Skill 可能包含恶意代码、过度权限请求、过时依赖等风险。在安装或使用前进行安全扫描，是保护 Agent 环境的第一道防线。本助手通过调用扫描 API，返回 Skill 的信任分、风险等级与详细安全报告。

本免费版聚焦于单次扫描与基础报告场景：输入解析、API 调用、五种判定结果处理、结构化报告输出。每种流程均提供明确的步骤指令与模板。

核心能力

能力一：Skill 标识解析

从用户输入中提取 owner/name 格式的 Skill 标识，校验格式合法性，处理异常输入。

输入: 用户提供能力一：Skill 标识解析所需的指令和必要参数。 处理: 解析能力一：Skill 标识解析的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力一：Skill 标识解析的响应数据,包含状态码、结果和日志。

能力二：扫描 API 调用

通过 WebFetch 或 curl 调用扫描 API，获取 Skill 的安全数据。提供主备调用方式，确保网络异常时仍可降级处理。

输入: 用户提供能力二：扫描 API 调用所需的指令和必要参数。 处理: 解析能力二：扫描 API 调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力二：扫描 API 调用的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

能力三：五种判定结果处理

根据 API 返回的 recommendation 字段，判定为五种结果之一，每种结果对应不同的报告模板与行为约束。

输入: 用户提供能力三：五种判定结果处理所需的指令和必要参数。 处理: 解析能力三：五种判定结果处理的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力三：五种判定结果处理的响应数据,包含状态码、结果和日志。 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：Agent、安装前的安全性、返回信任分、风险等级与详细报、安全扫描免费版是、一套面向独立开发、者与小型团队的、安全检测知识库、帮助用户在安装或、使用第三方、前快速评估其安全、核心能力、未扫描、错误处理与重试机、结构化、Markdown、报告输出等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

错误处理

API 调用可能因网络、限流、服务不可用等原因失败。本助手提供标准化的错误处理表与执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令策略。

输入: 用户提供错误处理所需的指令和必要参数。 处理: 解析错误处理的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回错误处理的响应数据,包含状态码、结果和日志。

能力五：结构化报告输出

将扫描结果格式化为结构化 Markdown 报告，包含信任分、风险分、置信度、能力摘要、权限要求、安全提示等关键字段。

输入: 用户提供能力五：结构化报告输出所需的指令和必要参数。 处理: 解析能力五：结构化报告输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力五：结构化报告输出的响应数据,包含状态码、结果和日志。

错误场景2

检查error_code并按照处理方式进行排查。

错误场景3

使用场景

依赖详情

开发者发现一个有用的 Skill，安装前调用本助手扫描其安全性，根据结果决定是否安装。

场景二：团队 Skill 准入审核

团队规定所有第三方 Skill 必须通过安全扫描才能引入。本助手提供标准化的扫描流程与报告存档。

场景三：个人 Skill 库复查

定期扫描已安装的 Skill，检查是否有新的安全风险（如过时、新发现的漏洞）。

场景四：批量 Skill 仓库审计

仓库维护者定期扫描收录的所有 Skill，清理高风险项目，保障仓库整体安全水位。

不适用场景

以下场景Skill安全扫描(免费版)不适合处理：

• 需要100%确定性的关键决策
• 医疗诊断
• 法律判决

触发条件

需要AI模型调用、智能对话、Agent编排、LLM应用时使用。不适用于非本工具能力范围的需求。

快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

本助手为指令型 Skill，通过 Agent 执行扫描流程。直接在对话中提供 Skill 标识即可。

典型提问模板：

帮我检查 anthropic/web-search 这个 Skill 是否安全

扫描一下 owner/repo 这个 Skill 的安全性

Agent 会按"输入解析 → API 调用 → 结果判定 → 报告输出"四步流程执行，并返回结构化的安全报告。

示例

输入解析流程

1. 从 $ARGUMENTS 提取 owner 和 name
2. 预期格式：owner/name（如 anthropic/web-search）
3. 若 $ARGUMENTS 为空或缺少 / 分隔符，询问用户：
   "请问要检查哪个 Skill？请以 owner/name 格式提供（如 anthropic/web-search）。"
4. 去除首尾空格，trim 后若任一部分为空则拒绝

扫描 API 调用

主调用方式（WebFetch）：
URL: https://scanner.pyxmate.com/api/v1/check/{owner}/{name}
Prompt: "Return the full JSON response body exactly as-is. Do not summarize."
# ...
备用方式（curl，WebFetch 不可用时）：
curl -s "https://scanner.pyxmate.com/api/v1/check/{owner}/{name}"

常见异常表

SAFE 判定报告模板

## Skill安全扫描：{owner}/{name}
# ...
**判定结果：SAFE** — 该 Skill 已通过扫描验证，可安全使用。
# ...
**信任分：** {trust_score}/10 | **风险分：** {risk_score}/10 | **置信度：** {confidence}%
**意图：** {intent} | **状态：** {status}
# ...
### 摘要
{summary}
# ...
### 详细信息
**用途：** {about.purpose}
**能力：** {about.capabilities as bullet list}
**所需权限：** {about.permissions_required as bullet list}
# ...
[查看完整报告]({detail_url}) | [徽章]({badge_url})

CAUTION 判定报告模板

## Skill安全扫描：{owner}/{name}(续1)
# ...
**判定结果：CAUTION** — 该 Skill 存在潜在风险，需要您的关注。
# ...
**信任分：** {trust_score}/10 | **风险分：** {risk_score}/10 | **置信度：** {confidence}%
# ...
### 摘要(补充)
{summary}
# ...
### 所需权限
{about.permissions_required as bullet list}
# ...
### 安全提示
{about.security_notes}
# ...
**是否要在警告评级下继续？请在安装或使用前明确确认。**

最佳实践

实践一：每次安装前必扫描

不要因为 Skill 来自知名作者就跳过扫描。供应链攻击可能影响任何项目，扫描是低成本高收益的防护措施。

实践二：CAUTION 必须人工确认

CAUTION 判定意味着存在潜在风险，不能自动放行。必须由用户明确确认后才继续安装，并记录确认人与确认时间。

实践三：FAILED 判定绝不软化

如果扫描结果为 FAILED（danger），直接报告危险，不要添加"但可能没问题"之类的软化措辞。安全判定必须客观严谨。

实践四：UNSCANNED 不等于安全

未扫描的 Skill 不代表安全，只是没有数据。应建议用户手动审查源码，或等待官方扫描完成后再使用。

实践五：报告字段按需展示

报告模板中提到的字段，若 API 返回为空则省略对应小节，不要展示"N/A"。保持报告简洁专业。

实践六：自扫描保持诚实

当扫描目标为本助手自身时，仍如实调用 API 并报告结果。若结果为 UNSCANNED，应坦诚说明"连安全扫描工具自身都尚未被扫描，我们言行一致——对待未扫描的 Skill 要谨慎"。

故障排查表

常见问题

Q1：扫描 API 需要密钥吗？

免费版不需要 API Key，直接调用公开端点即可。但可能有速率限制，短时间内大量请求会被限流。

Q2：信任分多少算安全？

通常信任分 ≥ 8 可视为较安全，5-8 需谨慎评估，<5 建议避免使用。但还需结合风险分与置信度综合判断。

Q3：扫描结果会过期吗？

会。Skill 更新后旧扫描结果可能失效，本助手会通过 is_outdated 字段判断是否过时，过时的 Skill 会标记为 OUTDATED。

Q4：FAILED 判定后还能用吗？

强烈不建议。FAILED 意味着扫描发现了明确危险信号，继续使用可能造成数据泄露、权限滥用等严重后果。如确需使用，必须由安全专家人工审查源码并签字确认。

Q5：批量扫描如何避免限流？

控制请求频率，建议每秒不超过 1 次请求。遇到 429 限流时等待 60 秒后重试。专业版提供批量扫描与队列调度能力。

Q6：如何提交未扫描的 Skill？

访问扫描服务官网，按指引提交 Skill 仓库地址。扫描完成后再次调用 API 即可获取结果。

依赖说明

运行环境

• Agent 平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• 网络: 需能访问 scanner.pyxmate.com

第三方依赖

API Key 配置

• 本免费版使用公开扫描端点，不需要 API Key
• 若调用专业版批量扫描接口，需配置扫描服务 API Key 于环境变量
• 禁止在 SKILL.md 或脚本中硬编码 API Token

可用性分类

• 分类: MD+EXEC（纯Markdown指令，需要exec命令行执行curl或WebFetch调用）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent执行安全扫描流程

已知限制

本免费体验版限制以下高级功能：

• 批量扫描与队列调度（仅专业版提供）
• 持续监控与变更通知（仅专业版提供）
• 自定义安全策略与白名单（仅专业版提供）
• 详细漏洞分析与修复建议（仅专业版提供）
• 团队协作与审计日志（仅专业版提供）

解锁全部功能请使用专业版：pyx-scanner-pro

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

输出格式

{
  "success": true,
  "data": {
    "result": "Skill安全扫描(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "pyx scanner"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}