PYX Scan , Agent Skill Safety Check

intent

scan an ai agent skill against the pyx scanner api to determine if it's safe to install or use. returns a verdict (safe, outdated, caution, failed, unscanned, or error) plus trust score, risk score, and actionable safety notes. use this when an agent or user needs to verify skill safety before integration, or when someone asks "is this safe", "check skill", "scan skill", "verify tool", or "pyx scan".

inputs

required parameters:

• $ARGUMENTS: skill identifier in owner/name format (e.g., anthropic/web-search). if missing or malformed, skill will prompt user for clarification.

external connections:

• pyx scanner api endpoint: https://scanner.pyxmate.com/api/v1/check/{owner}/{name}. no authentication required; endpoint is public. however, the api enforces rate limits (429 responses), so expect potential throttling if checking many skills in rapid succession.

tools:

• WebFetch (primary): fetch json from the pyx api endpoint.
• Bash(curl *) (fallback): execute curl if WebFetch unavailable.

procedure

step 1: parse input

• extract owner and name from $ARGUMENTS by splitting on /.
• trim whitespace from both parts.
• if $ARGUMENTS is empty, missing the / separator, or either part is empty after trimming, prompt the user: "which skill do you want to check? provide it as owner/name (e.g., anthropic/web-search)."
• output: validated owner and name strings.

step 2: call the pyx scanner api

• primary method: use WebFetch with url https://scanner.pyxmate.com/api/v1/check/{owner}/{name} and prompt "return the full json response body exactly as-is. do not summarize."
• if WebFetch fails (tool unavailable, network timeout, or any other failure), fall back immediately to bash: curl -s "https://scanner.pyxmate.com/api/v1/check/{owner}/{name}".
• output: raw json response body or error state (see step 3).

step 3: handle api errors

• map http status codes and network failures to verdicts:
  • 200: proceed to step 4.
  • 404: skill not in database. set verdict to unscanned.
  • 429: rate limited. set verdict to error with message "rate limited. try again shortly."
  • 5xx: server error. set verdict to error with message "pyx scanner is temporarily unavailable."
  • network failure (timeout, connection refused, dns failure): set verdict to error with message "could not connect to pyx scanner."
• output: verdict code and error message (if applicable), or parsed json response.

step 4: determine verdict

• read the recommendation field and is_outdated boolean from the json response.
• apply verdict logic:
  • if recommendation == "safe" and is_outdated == false: verdict = safe.
  • if recommendation == "safe" and is_outdated == true: verdict = outdated.
  • if recommendation == "caution": verdict = caution.
  • if recommendation == "danger": verdict = failed.
  • if recommendation == "unknown": verdict = unscanned.
  • if any other value or missing field: verdict = unscanned.
• output: verdict code and supporting data from json (trust_score, risk_score, confidence, intent, status, summary, about, scanned_commit, latest_commit, last_safe_commit, detail_url, badge_url).

step 5: output report

• format response as structured markdown (see output contract below).
• omit any section where the data is null, empty, or not present in the json.
• do not output raw json; always render as markdown.
• output: formatted markdown report.

decision points

if $arguments is missing or malformed: prompt user for owner/name format and wait for clarification. do not proceed to api call.

if webfetch fails: fall back to bash curl. do not retry WebFetch or ask the user to retry; assume WebFetch is unavailable and proceed with curl.

if both webfetch and curl fail: set verdict to error with the appropriate message (rate limited, server error, or could not connect).

if the verdict is caution: append an explicit confirmation prompt: "do you want to proceed despite the caution rating?" do not proceed to installation or use until the user confirms.

if the verdict is failed: never soften or qualify the warning. report danger as danger. do not suggest that it might be fine or that the user should try it anyway.

if the skill being scanned is pyx-scan itself (i.e., $arguments matches pyxmate/pyx-scan, pyxmate/pyx-scanner, or any variant referring to this skill): still call the api and report the verdict honestly. 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."

output contract

all output is formatted as structured markdown. the verdict code determines the template:

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
{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})

failed:

## 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})

unscanned:

## 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

error:

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

**Verdict: ERROR** ,  {error_message}

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

sections with null or empty values are omitted. markdown is always returned; raw json is never output.

outcome signal

the user knows the skill worked when:

• a clearly formatted markdown report appears with a verdict (safe, outdated, caution, failed, unscanned, or error).
• for safe, outdated, caution, and failed verdicts, the report includes trust score, risk score, and a summary.
• for caution verdicts, the user sees an explicit confirmation prompt.
• for failed verdicts, the warning is unambiguous and unsoftened.
• for unscanned verdicts, the user sees guidance on manual review and requesting a scan.
• for error verdicts, the user sees a specific error message (rate limited, server error, or connection failure).