🛡️ Skill Guardian

AI Agent Skill Security Scanner — detect prompt injection, malicious shell, supply chain attacks, and hidden Unicode threats in Claude Code / Codex / Cursor / Gemini CLI skills.

Why Skill Guardian?

36% of community skills contain security issues according to the Snyk ToxicSkills audit (Feb 2026). Agent Skills run with full user permissions — a malicious skill can read your SSH keys, exfiltrate source code, or establish persistence.

Skill Guardian scans skills before you install them, catching threats that manual review misses.

Quick Start

# Install
pip install skill-guardian

# Scan a skill before installing
skill-guardian scan github.com/some-user/some-skill

# Scan a local skill
skill-guardian scan ./my-skill/

# Audit all your installed skills
skill-guardian audit ~/.claude/skills/

# Initialize custom rules in your project
skill-guardian init

What It Detects

Layer	Name	Threats Detected
1	Metadata Integrity	Missing/invalid frontmatter, suspicious descriptions, excessive tool permissions
2	Hidden Characters	Unicode tags, zero-width chars, bidi overrides, homoglyph attacks, base64/hex payloads
3	Prompt Injection	Instruction override, goal hijacking, confused deputy, persistence attacks, data exfiltration
4	Malicious Shell	Reverse shells, data exfiltration, privilege escalation, crypto miners, command obfuscation, curl-bash
5	Supply Chain	Unpinned versions, typosquatted packages, known malicious dependencies
6	Behavioral Sandbox	Runtime behavior monitoring (coming soon)
7	Maintainer Reputation	Known threat actors, suspicious author names, throwaway repos

Output Formats

# Rich terminal output (default)
skill-guardian scan ./skill/

# JSON output (for automation)
skill-guardian scan ./skill/ -f json

# SARIF output (for GitHub Code Scanning / CI)
skill-guardian scan ./skill/ -f sarif -o report.sarif

# Fail CI on critical findings
skill-guardian scan ./skill/ --fail-on critical

Extensible Rule System

Add custom detection rules without writing Python code. Just drop a YAML file:

# rules/detect-internal-ips.yaml
name: "Internal IP Detection"
description: "Detects hardcoded internal IP addresses"
severity: medium
layer: 4
file_patterns:
  - "**/*.md"
  - "**/*.py"
patterns:
  - "10\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}"
  - "192\\.168\\.\\d{1,3}\\.\\d{1,3}"
suggestion: "Remove hardcoded internal IP addresses."
tags:
  - network
  - secrets

Three rule sources, auto-discovered:

1. Built-in Python rules — in skill_guardian/rules/*/
2. Built-in YAML patterns — in skill_guardian/rules/patterns/
3. Your custom rules — in ~/.skill-guardian/rules/ or project rules/

CI Integration

# .github/workflows/skill-audit.yml
name: Skill Security Audit
on: [push, pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install skill-guardian
      - run: skill-guardian scan ./skills/ --fail-on high

Scoring

Each skill receives a 0-100 score and A-F grade:

Grade	Score	Meaning
A	95–100	Clean — safe to install
B	80–94	Minor issues — likely safe
C	65–79	Warning — review before installing
D	50–64	High risk — not recommended
F	0–49	Critical — do not install

Roadmap

• 7-layer detection engine
• CLI with rich terminal output
• JSON / SARIF export
• Extensible YAML rule system
• Community rule directory support
• Docker sandbox (Layer 6 runtime analysis)
• Web registry at skillguardian.dev
• VS Code extension
• GitHub Action (pre-built)
• NPM/pypi package age API integration
• CVE database cross-reference
• ML-based injection classifier

Contributing

Contributions welcome! Areas to help:

• New detection rules — YAML patterns or Python rules
• Language support — improve parsers for more dependency formats
• Documentation — tutorials, threat reports, blog posts
• Bug reports — found a false positive or missed threat? Open an issue.

License

MIT © Skill Guardian Contributors