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

What it detects

22 rules across 5 categories:

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.