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
$ARGUMENTSis empty or missing the/separator, ask the user: "Which skill do you want to check? Provide it asowner/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:
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
- Always call the API — never skip the check or return a cached/assumed result.
- Never soften a FAILED verdict — if the scan says danger, report danger. Do not add qualifiers like "but it might be fine."
- Always ask user confirmation on CAUTION — the user must explicitly agree before proceeding.
- Keep reports concise — omit null/empty sections rather than showing "N/A."
- 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."
