agent-skill-scanner
Scan agent skill files for security vulnerabilities. 22 detection rules across prompt injection, capability escalation, data exfiltration, encoded payloads, and composition risks.
Built for OpenClaw and MCP skill files. Generic SAST tools (semgrep, CodeQL) produce zero detections on these formats because they lack rules for markdown-embedded code and YAML skill definitions. This scanner fills that gap.
Install
pip install agent-skill-scanner
Usage
Scan a directory of skill files:
agent-skill-scan scan --path ./skills/
Example output:
Skill Findings Severity
--------------------------------------------------------------
anti-injection-skill 9 CRITICAL
askhuman 3 CRITICAL
azure-devops 1 HIGH
curl-http 3 CRITICAL
deploy-agent 0 CLEAN
--------------------------------------------------------------
TOTAL 16
Scanned 5 skills, 16 findings.
Findings by category:
prompt_injection: 6
capability_escalation: 5
data_exfiltration: 3
encoded_payload: 2
Options
agent-skill-scan scan --path ./skills/ --output json # JSON output for CI
agent-skill-scan scan --path ./skills/ --quiet # Exit code only (0=clean, 1=findings)
agent-skill-scan scan --path ./skills/ --min-severity HIGH # Filter by severity
agent-skill-scan scan --path ./skill.md # Scan a single file
Exit codes
| Code | Meaning |
|---|---|
| 0 | No HIGH or CRITICAL findings |
| 1 | HIGH or CRITICAL findings detected |
What it detects
22 rules across 5 categories:
| Category | Rules | Examples |
|---|---|---|
| Prompt injection | 5 | System prompt override, role hijacking, instruction injection |
| Capability escalation | 5 | Privilege escalation commands, shell spawning, persistence mechanisms |
| Data exfiltration | 4 | Credential access, environment variable reads, outbound data transfer |
| Encoded payloads | 4 | Base64 encoded commands, hex payloads, obfuscated strings |
| Composition risks | 4 | Unrestricted tool chaining, cross-skill data flow, trust boundary violations |
How it works
The scanner parses agent skill files (SKILL.md, MCP tool definitions, YAML configs with name:/description: frontmatter) and runs pattern-based detection against code blocks, full text, and structured fields. Rules are defined in YAML and can be extended.
Research
This scanner was built from findings in the agent-skill-scanner research project. The core finding: generic SAST tools produce zero detections on agent skill files (McNemar chi2=9.09, p=0.003). The gap is structural — no existing rules target markdown/YAML skill formats.
Limitations
- Pattern-based detection only — no semantic analysis or LLM-powered reasoning
- Designed for OpenClaw SKILL.md and MCP tool definitions — may miss formats from other agent frameworks
- Rules cover known attack patterns from published research, not zero-days
- False positives possible on skills that legitimately use system commands
License
MIT — Rex Coleman, 2026
More research at rexcoleman.dev.
Metadata
Release files for agent-skill-scanner 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_skill_scanner-0.1.0.tar.gz | 16.2 kB | Without provenance | Details for agent_skill_scanner-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_skill_scanner-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agent_skill_scanner-0.1.0-py3-none-any.whl |
Total release size: 33.7 kB
Release files / agent_skill_scanner-0.1.0.tar.gz
| Download URL | agent_skill_scanner-0.1.0.tar.gz |
|---|---|
| Size | 16.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0158b9fe79393840dd90459df80a114c9d259368ebfbfde5b2af2bafec83012b
|
|
BLAKE2b-256 checksum How to use checksums |
1f9da0d81c5796eb8bfcb157601734fe244b74b4a350e7bd99d372aef15999e8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.11
|
Release files / agent_skill_scanner-0.1.0-py3-none-any.whl
| Download URL | agent_skill_scanner-0.1.0-py3-none-any.whl |
|---|---|
| Size | 17.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eb8edcbf153849510dd4fdf2733934cd91a369171c0034fbdcec9412985c312b
|
|
BLAKE2b-256 checksum How to use checksums |
50c09c65f9d0ab66c1b67530e8b88c53eed676814ebfbf8cfc3807c99c7d7c0e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.11
|
Security for agent-skill-scanner 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.