Install

# npm -- JavaScript/TypeScript CLI + library
npm install --save-dev skillguard-cli

# PyPI -- Python CLI + library, a genuine port, not a wrapper around the Node binary
pip install skillguard-cli

Neither install fetches anything at scan time: all ten rule packs and the pattern-matching engine ship inside the npm tarball and the Python wheel alike.

Try it now

npx skillguard-cli scan ./examples/known-bad-skill

This runs against a fixture bundled with the repo, safe, non-functional, and deliberately pattern-matchable, and returns 11 real findings with file:line citations in about 0.15 seconds.

[!NOTE] Every scan prints Loading SkillGuard rule packs... to stderr first. That's expected startup output, not a hang.

Compare it against a clean fixture:

npx skillguard-cli scan ./examples/clean-skill

which returns zero findings and exit code 0.

Why this exists

Third-party agent skills run with real tool, file, and network permissions the moment they're installed, and almost nothing checks them first. Snyk's ToxicSkills study scanned 3,984 publicly listed skills in February 2026 and found security flaws in 36% of them, including 76 skills carrying confirmed malicious payloads: credential theft, reverse shells, data exfiltration. Most marketplaces and agent frameworks have no scan step between "someone published a skill" and "a user's agent runs it." SkillGuard is that step: a CLI, a library, an MCP server, and a GitHub Action, all reading the same ten bundled rule packs.

Features

• Ten purpose-built rule categories (SG01-SG10), covering network mismatch, remote code execution, file-scope escalation, hook supply-chain risk, obfuscated payloads, credential harvesting, frontmatter-scope spoofing, prompt injection embedded in a skill's own instructional text, cross-skill privilege chaining, and marketplace typosquatting. Every category is documented rule-by-rule in CHANGELOG.md.
• Cross-skill privilege chaining (scan-set) catches a threat single-skill scanners structurally miss: skill A reads sensitive files, skill B has network egress, neither declares sandboxing between them, and combined they can exfiltrate what skill A alone could only read. npx skillguard-cli scan-set ./my-skills-dir scans every skill in a directory and flags the combination. Snyk Agent Scan's own maintainers confirmed in issue #301 that their --skills flag only recognizes one SKILL.md at a time and doesn't recursively discover skills in a directory at all, so this is not a feature SkillGuard is claiming to do better, it's one no other skill scanner we found does yet.
• Zero auth, zero config. npx skillguard-cli scan <path> needs no account, no API token, no signup. Compare that to Snyk Agent Scan (SNYK_TOKEN and a Snyk account) or Socket CLI (SOCKET_CLI_API_TOKEN for full functionality).
• Callable as an MCP tool, not just a CLI. npx skillguard-cli mcp starts a stdio MCP server exposing a scan_skill tool, so Claude Code, Cursor, or any orchestrating agent can scan a downloaded skill as a tool call before installing or running it, no subprocess, no stdout parsing. Verified with a real JSON-RPC initialize / tools/list / tools/call handshake against the built server.
• Two independent, equally maintained distributions. The npm package and the PyPI package read the same rule-pack contract and produce matching findings against the same target; neither is a wrapper around the other.
• Nothing fetched over the network at scan time. All rule packs ship inside the package itself, so a scan of untrusted content never reaches out to anything the content controls.

Quickstart

npx skillguard-cli scan ./my-skill --format json --severity-threshold MEDIUM

import { scanSkill } from 'skillguard-cli';

const result = await scanSkill('./my-skill', { severityThreshold: 'HIGH' });
if (result.exitCode === 1) {
  console.log(`${result.findings.length} finding(s) at or above HIGH`);
}

from skillguard import scan_skill, ScanOptions

result = scan_skill("./my-skill", ScanOptions(severity_threshold="HIGH"))
if result.exit_code == 1:
    print(f"{len(result.findings)} finding(s) at or above HIGH")

Commands

npx skillguard-cli <command> [options]
# Python: skillguard <command> [options]

Flags shared by scan and scan-set (verified against src/cli.ts and skillguard/cli.py):

Exit codes: 0 clean scan. 1 a finding at or above the severity threshold. 2 the target path doesn't exist, or (for scan) no skill files were found.

API reference

TypeScript (src/index.ts), re-exported from the npm package's root import:

import { scanSkill, scanSkillSet, discoverSkillDirs, computeCrossSkillFindings } from 'skillguard-cli';

scanSkill(path: string, options?: ScanOptions): Promise<ScanResult>
scanSkillSet(dir: string, options?: ScanOptions): Promise<SkillSetScanResult>

scanSkill() runs the same scan logic as scan; scanSkillSet() runs the same logic as scan-set. Both return a structured result (findings, timeouts, warnings, exitCode) instead of throwing, so a caller embedding SkillGuard never has to wrap it in a try/catch just to get a verdict. Finding, ScanOptions, ScanResult, ScanWarning, Severity, OutputFormat, RuleCategory, SkillEntry, and SkillSetScanResult types ship alongside.

Python (python/src/skillguard/__init__.py):

from skillguard import scan_skill, scan_skill_set, discover_skill_dirs, compute_cross_skill_findings, ScanOptions

scan_skill(path: str, options: ScanOptions | None = None) -> ScanResult
scan_skill_set(dir: str, options: ScanOptions | None = None) -> SkillSetScanResult

Same shape, snake_case naming. One honest gap worth stating plainly: the Python package's scan_skill_set() runs the same cross-skill-chaining orchestration the npm package's scanSkillSet() does, but the npm package additionally runs a second, narrower SG09 check inside a normal single-skill scan (a sibling-path reference heuristic, src/ast/cross-skill-chaining.ts) that has no Python equivalent yet. If you rely on cross-skill detection from a single scan call rather than scan-set, that path is TypeScript-only today.

MCP server (agent-native, tool-call)

npx skillguard-cli mcp

Starts SkillGuard as a stdio MCP server exposing one tool, scan_skill ({ path, severityThreshold?, timeoutMs? }), so another agent, Claude Code, Cursor, an orchestrator, can scan a third-party skill directly as a tool call before installing or running it. Verified in this update with a real handshake: initialize returns real server info, tools/list returns the real scan_skill schema, and tools/call against ./examples/known-bad-skill returns the same 11 findings the CLI reports. Client config example:

Read the full README on GitHub →