scan_skill
Scans an untrusted AI agent-skill directory for known attack patterns before installing or running it. Returns findings and severity to flag risks.
Instructions
Scans a third-party AI agent-skill directory (a SKILL.md manifest plus its bundled hooks/scripts) for known attack patterns before that skill is installed or executed: remote-code-execution hooks (SG02), file-scope escalation (SG03), supply-chain-risky install hooks (SG04), obfuscated payloads (SG05), credential harvesting (SG06), frontmatter spoofing (SG07), prompt injection in the skill's own instructional text (SG08), and marketplace typosquatting (SG10). Call this before installing or running any agent skill you did not author yourself -- the same way you would not execute an unreviewed shell script from a stranger; it has nothing useful to do on skills you already trust.
This is a read-only, offline, side-effect-free operation: every rule pack ships inside the installed wheel, so no network call happens at scan time, and the target's own files are only ever read and pattern-matched, never eval()'d, exec()'d, or imported. Re-running it on an unchanged target is idempotent. Two suppression mechanisms exist in the underlying CLI (.skillguardignore and inline "# skillguard-ignore: SGxx" comments) but this tool never honors either, even if the target ships its own .skillguardignore -- every call runs at full strictness since the target is by definition untrusted. One coverage gap: SG09 (cross-skill privilege chaining across a set of skills) only runs through the separate scan_skill_set()/scan-set CLI path, not through this single-directory tool. An invalid path or unreadable target raises an error rather than returning a silently-clean result.
Parameters: path (string, required) is the filesystem path to the skill directory to scan, e.g. "/skills/pdf-tools" containing SKILL.md plus its hooks/. severity_threshold (string, optional, one of HIGH/MEDIUM/LOW, default HIGH) is the minimum finding severity that flips the result's exit code to non-zero -- lower it to MEDIUM or LOW for a stricter review. timeout_ms (integer, optional, default 10000) caps the per-file scan time in milliseconds; files that exceed it land in the result's timeouts list instead of failing the whole scan. Example calls: {"path": "/skills/pdf-tools"} for a default HIGH-severity scan; {"path": "/skills/pdf-tools", "severity_threshold": "LOW"} to surface every finding; {"path": "/skills/pdf-tools", "timeout_ms": 30000} for a larger skill that needs more per-file time.
Returns a JSON string with: target (the scanned path), filesScanned, severityThreshold, exitCode (0 = clean, 1 = a finding at/above threshold was found, 2 = target/config error), summary (finding counts by severity), findings (a list of {ruleId, category, severity, message, file, line, snippet?}), timeouts (files that hit the per-file limit), unscannedFiles (recognized-but-unsupported-language files), and warnings ({code, message} entries, e.g. for an invalid rule pack). A non-zero exitCode means the skill tripped a finding at or above the configured threshold and should not be trusted without human review.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| timeout_ms | No | ||
| severity_threshold | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |