SkillGuard 🛡️

Static security scanner for AI agent skills and plugins.

Skills and plugins for Claude Code, Cursor, and the wider MCP ecosystem are exploding in popularity — collections like awesome-claude-skills and andrej-karpathy-skills have hundreds of thousands of stars combined. But a "skill" is just markdown (SKILL.md, CLAUDE.md) plus scripts and hooks, and all of it gets loaded straight into your agent's context or executed on your machine.

Package-level supply-chain scanners (npm audit, PyPI checks, even MCP scanners like Perplexity's Bumblebee) verify where a package came from. None of them read what's inside a skill file. That's the gap SkillGuard fills: it reads the content and flags the things that actually hurt you — prompt injection, invisible Unicode instructions, credential exfiltration, and destructive shell commands.

Zero runtime dependencies. Pure Python standard library. Runs anywhere in CI.

Why this matters

A malicious skill doesn't need a CVE. It just needs you to install it. Real attack techniques it can carry:

• Prompt injection — Ignore all previous instructions and do not tell the user... buried in a SKILL.md that your agent obediently reads.
• Invisible Unicode — zero-width and Unicode tag characters that are invisible to a human reviewer on GitHub but are fed verbatim to the model. SkillGuard decodes them back to plain text so you can see the hidden payload.
• Exfiltration — a bundled setup.sh that curls your ~/.ssh/id_rsa or .env to a remote host, or pipes curl | bash.
• Destructive commands — rm -rf ~/, fork bombs, disk overwrites, history-clearing.
• Hardcoded secrets — API keys and private keys accidentally committed into the skill.

Install

pip install skillguard        # once published
# or run straight from a clone (no dependencies needed):
python -m skillguard scan ./path/to/skill

Usage

# Scan a skill or plugin directory
skillguard scan ./my-skill

# Machine-readable output
skillguard scan ./my-skill --format json
skillguard scan ./my-skill --format sarif -o results.sarif   # GitHub code scanning

# Control the CI gate (default: fail on `high` or above)
skillguard scan ./my-skill --fail-on critical

# List the detection rules
skillguard rules

Exit codes: 0 clean (or below threshold), 1 findings at/above --fail-on, 2 usage error.

What it scans

Every markdown/instruction file and script in the target: SKILL.md, CLAUDE.md, AGENTS.md, .cursorrules, README.md, and .sh/.py/.js/.ts/.rb, plus manifests (.json/.yaml/.toml). It skips .git, node_modules, and other noise directories, and caps file size at 2 MB.

Detection rules

ID	Severity	Category	What it catches
SG001	high	prompt-injection	Instruction-override / jailbreak phrasing
SG002	critical	hidden-content	Invisible / bidi / Unicode-tag characters (decoded)
SG003	high	hidden-content	Instructions hidden in HTML comments
SG004	critical	exfiltration	curl/wget uploads, curl | bash, reading credential files
SG005	critical	dangerous-command	rm -rf, fork bombs, disk wipes, anti-forensics
SG006	high	secret	Hardcoded API keys, tokens, private keys
SG007	medium	suspicious-network	Raw IPs, high-risk TLDs, URL shorteners

Use as a GitHub Action

name: skill-security
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: praneel95/skillguard@v0.1.0
        with:
          path: .
          fail-on: high
          format: sarif
          output: skillguard.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with: { sarif_file: skillguard.sarif }

Or call the module directly without the Action:

      - run: python -m skillguard scan . --fail-on high

Use as a pre-commit hook

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/praneel95/skillguard
    rev: v0.1.0
    hooks:
      - id: skillguard

Then pre-commit install. SkillGuard now scans on every commit and blocks anything at high severity or above.

How it's built

• skillguard/rules.py — the detection engine. Each rule is a small, isolated detector; add one by appending to RULES.
• skillguard/scanner.py — walks a directory, applies rules, computes a 0–100 risk score.
• skillguard/report.py — terminal, JSON, and SARIF 2.1.0 renderers.
• skillguard/cli.py — the skillguard command.
• examples/ — a benign skill and a deliberately malicious one used by the tests.
• tests/ — 15 unit tests covering every rule (python tests/test_rules.py).

Testing

python tests/test_rules.py     # no test dependencies required

Scope and honesty

SkillGuard is a fast first-pass static analyzer, not a guarantee. It uses pattern-based heuristics, so it can produce false positives (a security tutorial that documents rm -rf) and can't catch every obfuscation. Treat a clean result as "nothing obvious found," not "provably safe." Review high-risk skills by hand.

License

MIT