skill-guard

Local-first security scanner for AI Skill bundles. Catches malicious code, supply-chain attacks, and prompt injection before a Skill ever reaches a user. Pure static analysis — sub-2-second, zero LLM cost.

72 built-in rules · 4 platform adapters (Niuma / OpenClaw / MCP / GPTs Actions) · terminal / JSON / SARIF output · fail-closed by design.

This repo is the open-source local CLI. The hosted SaaS at skillguard.vip adds Layer-3 LLM review, regular rule updates, and the public Safe Rank leaderboard on top.

Install

# One-off, no install (resolves directly from this repo)
npx -y github:yangyixxxx/skillguard scan ./my-skill

# Global install (npm package: skill-guard)
npm i -g skill-guard
skill-guard scan ./my-skill

Requires Node.js ≥ 20.

npm package name is skill-guard (with a hyphen). The GitHub repo lives at yangyixxxx/skillguard (no hyphen) for historical reasons — both refer to the same project.

Usage

# Scan a directory
skill-guard scan ./my-skill

# JSON output
skill-guard scan --format json ./my-skill > report.json

# SARIF (paste into GitHub Code Scanning)
skill-guard scan --format sarif ./my-skill > results.sarif

# Tighten the failure threshold (default 70)
skill-guard scan --threshold 50 ./my-skill

# Render a metadata card from a saved report id
skill-guard report ./my-skill

Exit code: 0 if score ≥ threshold and no hard-trigger fired; 1 otherwise. Use it directly in CI:

# .github/workflows/skill-review.yml
- run: npx -y skill-guard scan ./my-skill --format sarif > results.sarif
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: results.sarif }

What it actually checks

Layer 0 — Structure. File-count / size limits, path traversal, symlinks, binary blob detection, YAML frontmatter validation, allowed-tools whitelist.

Layer 1 — Rules. 72 patterns split into:

• 22 hard-blocks that single-handedly fail the bundle (rm -rf /, curl … | sh, hard-coded sk-… API keys, eval injection, SSH/AWS credential reads, …)
• 50 weighted rules scored on an exponential-decay curve across files; context-aware (code vs. docs).

Layer 2 — Dependencies. Extracts every Python import, Node require, Cargo crate, env-var reference, and cross-checks against PyPI / npm / Cargo whitelists for typosquats.

If rules can't load or a scan times out, the CLI refuses to ship a passing report — it would rather block one second longer than slip through with a fake green check.

Self-hosting from source

git clone https://github.com/yangyixxxx/skillguard.git
cd skillguard
pnpm install
pnpm run build         # regenerates dist/skill-guard.mjs
node ./dist/skill-guard.mjs scan ./my-skill

The pre-built dist/skill-guard.mjs (~300 KB) is committed so npx github:… works without a build step.

SaaS extras (skillguard.vip)

| | Local CLI (this repo) | SaaS | |---|---|---| | Layer 0–2 static scan | ✅ offline | ✅ | | terminal / JSON / SARIF | ✅ | ✅ | | GitHub Action / MCP integration | ✅ | ✅ | | Layer 3 LLM review (semantic, catches what regex misses) | ❌ | ✅ built-in (no key required) | | Rolling rule updates (new attack patterns, weekly) | 🟡 repo snapshot | ✅ | | Safe Rank public skill leaderboard | ❌ | ✅ | | Scan history / audit log | ❌ | ✅ | | Bring your own LLM (Anthropic / OpenAI / vLLM) | ❌ | ✅ Pro+ | | SSO / SLA / self-hosted | ❌ | ✅ Enterprise |

Free tier on the SaaS: 30 scans + 3 LLM reviews / month, no credit card. Try at https://skillguard.vip.

License

This package is Apache-2.0. The SaaS server code (in the upstream monorepo at yangyixxxx/skill-guard) is AGPL-3.0. CLI / adapters / core engine are deliberately permissive so you can drop them into any pipeline, paid or not.

Contributing

The canonical source of truth is the upstream monorepo — this repo is a synced subset for npm distribution. To propose rule changes, new adapters, or CLI features, file issues / PRs at yangyixxxx/skill-guard.