pyx-scan

在安装或使用AI代理技能之前，请先检查该技能是否安全。 调用 PYX 扫描仪 API 来检索信任状态、风险评分和安全性 推荐。当代理需要验证技能安全或用户说时使用 “这样安全吗”、“检查技能”、“扫描技能”、“验证工具”、“pyx 扫描”。

# PYX Scan — Agent Skill Safety Check

Verify whether an AI agent skill is safe before installing or using it by querying the PYX Scanner API.

## Workflow

### Step 1: Parse Input

Extract `owner` and `name` from `$ARGUMENTS`.

- Expected format: `owner/name` (e.g., `anthropic/web-search`)
- If `$ARGUMENTS` is empty or missing the `/` separator, ask the user:
  *"Which skill do you want to check? Provide it as `owner/name` (e.g., `anthropic/web-search`)."*
- Trim whitespace. Reject if either part is empty after trimming.

### Step 2: Call the PYX Scanner API

Fetch the safety data:

```
WebFetch URL: https://scanner.pyxmate.com/api/v1/check/{owner}/{name}
Prompt: "Return the full JSON response body exactly as-is. Do not summarize."
```

If `WebFetch` fails (tool unavailable, network error), fall back to:

```bash
curl -s "https://scanner.pyxmate.com/api/v1/check/{owner}/{name}"
```

### Step 3: Handle Errors

| HTTP Status | Meaning | Action |
|---|---|---|
| **200** | Skill found | Proceed to Step 4 |
| **404** | Skill not in database | Verdict = **UNSCANNED** |
| **429** | Rate limited | Verdict = **ERROR** — "Rate limited. Try again shortly." |
| **5xx** | Server error | Verdict = **ERROR** — "PYX Scanner is temporarily unavailable." |
| Network failure | Cannot reach API | Verdict = **ERROR** — "Could not connect to PYX Scanner." |

### Step 4: Determine Verdict

Use the JSON response fields to determine the verdict:

| Condition | Verdict |
|---|---|
| `recommendation == "safe"` AND `is_outdated == false` | **SAFE** |
| `recommendation == "safe"` AND `is_outdated == true` | **OUTDATED** |
| `recommendation == "caution"` | **CAUTION** |
| `recommendation == "danger"` | **FAILED** |
| `recommendation == "unknown"` | **UNSCANNED** |

### Step 5: Output Report

Format the report as structured markdown. Omit any section where the data is null or empty.

**For SAFE verdict:**

```
## PYX Scan: {owner}/{name}

**Verdict: SAFE** — This skill has been scanned and verified safe.

**Trust Score:** {trust_score}/10 | **Risk Score:** {risk_score}/10 | **Confidence:** {confidence}%
**Intent:** {intent} | **Status:** {status}

### Summary
{summary}

### About
**Purpose:** {about.purpose}
**Capabilities:** {about.capabilities as bullet list}
**Permissions Required:** {about.permissions_required as bullet list}

[View full report]({detail_url}) | [Badge]({badge_url})
```

**For OUTDATED verdict:**

```
## PYX Scan: {owner}/{name}

**Verdict: OUTDATED** — Last scan was safe, but the skill has been updated since.

The scanned commit (`{scanned_commit}`) no longer matches the latest (`{latest_commit}`).
The new version has NOT been reviewed. Proceed with caution.

**Trust Score:** {trust_score}/10 | **Risk Score:** {risk_score}/10
**Last Safe Commit:** {last_safe_commit}

### Summary
{summary}

[View full report]({detail_url})
```

**For CAUTION verdict:**

```
## PYX Scan: {owner}/{name}

**Verdict: CAUTION** — This skill has potential risks that need your attention.

**Trust Score:** {trust_score}/10 | **Risk Score:** {risk_score}/10 | **Confidence:** {confidence}%
**Intent:** {intent} | **Status:** {status}

### Summary
{summary}

### About
**Purpose:** {about.purpose}
**Permissions Required:** {about.permissions_required as bullet list}
**Security Notes:** {about.security_notes}

**Do you want to proceed despite the caution rating?** Please confirm before installing or using this skill.

[View full report]({detail_url})
```

**For FAILED verdict:**

```
## PYX Scan: {owner}/{name}

**Verdict: FAILED** — This skill has been flagged as dangerous. Do NOT install or use it.

**Trust Score:** {trust_score}/10 | **Risk Score:** {risk_score}/10 | **Confidence:** {confidence}%
**Intent:** {intent} | **Status:** {status}

### Summary
{summary}

### About
**Security Notes:** {about.security_notes}

[View full report]({detail_url})
```

**For UNSCANNED verdict:**

```
## PYX Scan: {owner}/{name}

**Verdict: UNSCANNED** — This skill has not been scanned by PYX Scanner.

No safety data is available. You should:
1. Review the skill's source code manually before use
2. Check the skill's repository for known issues
3. Request a scan at https://scanner.pyxmate.com
```

**For ERROR verdict:**

```
## PYX Scan: {owner}/{name}

**Verdict: ERROR** — {error_message}

Safety could not be verified. Treat this skill as unverified until you can confirm its safety.
```

## Behavioral Rules

1. **Always call the API** — never skip the check or return a cached/assumed result.
2. **Never soften a FAILED verdict** — if the scan says danger, report danger. Do not add qualifiers like "but it might be fine."
3. **Always ask user confirmation on CAUTION** — the user must explicitly agree before proceeding.
4. **Keep reports concise** — omit null/empty sections rather than showing "N/A."
5. **No raw JSON** — always format the response as the structured markdown report above.

## Self-Scan Awareness

When `$ARGUMENTS` is `pyxmate/pyx-scan`, `pyxmate/pyx-scanner`, or refers to this skill itself, still call the API honestly and report whatever comes back. If the result is UNSCANNED, append:

> *"Yes, even the security scanner's own skill hasn't been scanned yet. We practice what we preach — treat unscanned skills with caution."*

---

## 中文说明

# PYX Scan — 代理技能安全检查

在安装或使用某个 AI 代理技能之前，通过查询 PYX Scanner API 来验证该技能是否安全。

## 工作流程

### 第 1 步：解析输入

从 `$ARGUMENTS` 中提取 `owner` 和 `name`。

- 预期格式：`owner/name`（例如 `anthropic/web-search`）
- 如果 `$ARGUMENTS` 为空或缺少 `/` 分隔符，请询问用户：
  *"Which skill do you want to check? Provide it as `owner/name` (e.g., `anthropic/web-search`)."*
- 去除首尾空白。若去除空白后任一部分为空，则拒绝。

### 第 2 步：调用 PYX Scanner 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."
```

如果 `WebFetch` 失败（工具不可用、网络错误），回退到：

```bash
curl -s "https://scanner.pyxmate.com/api/v1/check/{owner}/{name}"
```

### 第 3 步：处理错误

| HTTP 状态码 | 含义 | 操作 |
|---|---|---|
| **200** | 找到技能 | 进入第 4 步 |
| **404** | 技能不在数据库中 | 裁定结果 = **UNSCANNED** |
| **429** | 触发限流 | 裁定结果 = **ERROR** — "Rate limited. Try again shortly." |
| **5xx** | 服务器错误 | 裁定结果 = **ERROR** — "PYX Scanner is temporarily unavailable." |
| 网络故障 | 无法访问 API | 裁定结果 = **ERROR** — "Could not connect to PYX Scanner." |

### 第 4 步：确定裁定结果

使用 JSON 响应字段来确定裁定结果：

| 条件 | 裁定结果 |
|---|---|
| `recommendation == "safe"` 且 `is_outdated == false` | **SAFE** |
| `recommendation == "safe"` 且 `is_outdated == true` | **OUTDATED** |
| `recommendation == "caution"` | **CAUTION** |
| `recommendation == "danger"` | **FAILED** |
| `recommendation == "unknown"` | **UNSCANNED** |

### 第 5 步：输出报告

将报告格式化为结构化的 markdown。对于数据为 null 或为空的部分，请省略。

**对于 SAFE 裁定结果：**

```
## PYX Scan: {owner}/{name}

**Verdict: SAFE** — This skill has been scanned and verified safe.

**Trust Score:** {trust_score}/10 | **Risk Score:** {risk_score}/10 | **Confidence:** {confidence}%
**Intent:** {intent} | **Status:** {status}

### Summary
{summary}

### About
**Purpose:** {about.purpose}
**Capabilities:** {about.capabilities as bullet list}
**Permissions Required:** {about.permissions_required as bullet list}

[View full report]({detail_url}) | [Badge]({badge_url})
```

**对于 OUTDATED 裁定结果：**

```
## PYX Scan: {owner}/{name}

**Verdict: OUTDATED** — Last scan was safe, but the skill has been updated since.

The scanned commit (`{scanned_commit}`) no longer matches the latest (`{latest_commit}`).
The new version has NOT been reviewed. Proceed with caution.

**Trust Score:** {trust_score}/10 | **Risk Score:** {risk_score}/10
**Last Safe Commit:** {last_safe_commit}

### Summary
{summary}

[View full report]({detail_url})
```

**对于 CAUTION 裁定结果：**

```
## PYX Scan: {owner}/{name}

**Verdict: CAUTION** — This skill has potential risks that need your attention.

**Trust Score:** {trust_score}/10 | **Risk Score:** {risk_score}/10 | **Confidence:** {confidence}%
**Intent:** {intent} | **Status:** {status}

### Summary
{sum