Skillguard

[Terminal recording of installing skillguard-cli with npm and running its first scan against examples/known-bad-skill, reporting 11 findings]

Install

# npm -- JavaScript/TypeScript CLI + librarynpm install --save-dev skillguard-cli
# PyPI -- Python CLI + library, a genuine port, not a wrapper around the Node binarypip 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

[Terminal recording of npx skillguard-cli scan run with --format json, showing the structured JSON findings output a script or agent can parse directly]

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]

[Terminal recording of npx skillguard-cli scan-set run against a two-skill directory, reporting a HIGH SG09 cross-skill-privilege-chaining finding between a filesystem-reading skill and a network-egress skill]

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) -> ScanResultscan_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:

{ "mcpServers": { "skillguard": { "command": "npx", "args": ["skillguard-cli", "mcp"] } } }

Full setup, the tool's input/output schema, and the security guarantees this path preserves (same .skillguardignore/inline-suppression defaults as the CLI, no way to pass an ignore path through the tool) are in docs/integrations/mcp.md. The Python package ships the identical tool via skillguard mcp (requires the optional mcp extra, pip install "skillguard-cli[mcp]", Python >=3.10): native and in-process, calling scan_skill() directly, no subprocess and no stdout/JSON parsing surface. uvx can run it without a manual install step, which is the recommended way to wire it into Claude Desktop:

{  "mcpServers": {    "skillguard": {      "command": "uvx",      "args": ["--from", "skillguard-cli", "skillguard", "mcp"]    }  }}

GitHub Action

- name: SkillGuard  uses: RudrenduPaul/skillguard@main  with:    path: ./my-skill    severity-threshold: HIGH

The Action defaults to --format sarif and uploads results straight to GitHub code scanning. The bare CLI keeps a human-readable default, since a terminal and a CI log want different things.

Rule packs

Every rule pack lives under rulepacks/ (npm) and python/src/skillguard/rulepacks/data/ (Python), kept in sync by hand and covered by CONTRIBUTING.md's parity rule. Nothing is fetched over the network at scan time.

SG05 known limitation: obfuscation detection under pure static analysis has a materially higher false-negative rate than the other categories. SG05 catches known, common encoding/eval idioms; treat it as best-effort coverage, not a complete answer to obfuscation.

How SkillGuard compares

SkillGuard is purpose-built for the agent-skill threat model, frontmatter-declared scope versus actual behavior, hook-level supply-chain risk, cross-skill privilege combination, and credential-harvesting patterns specific to how skills are packaged and installed. That's a narrower job than a general-purpose scanner, and this table says so plainly rather than implying SkillGuard beats tools built for a different job.

A few honest notes, since a security tool's credibility depends on saying the unflattering parts out loud:

• Snyk Agent Scan is the closest real competitor, more mature (2,897 stars vs. SkillGuard's 1) and covering more overall ground (15+ detection categories, plus MCP server config scanning, which SkillGuard does not do). The real differences are the auth story (SkillGuard needs zero signup or token) and cross-skill analysis (Snyk's own maintainers confirmed their tool is single-file today). If you already have a Snyk account and want MCP-server coverage too, Agent Scan covers more ground; if you want a zero-auth check that can also reason about a whole directory of skills at once, that's what SkillGuard is for.
• SkillGuard does not wrap Semgrep. It ships its own small, in-process pattern engine (Semgrep-inspired, not Semgrep) so the npx install never depends on a Python/PyPI toolchain. If you need true multi-language, general-purpose static analysis across 30+ languages, Semgrep is the more mature tool for that job.
• Socket CLI is an adjacent category, not a direct competitor. It's built for typosquats and malicious install scripts across npm/PyPI packages, not a skill's own SKILL.md frontmatter and declared-versus-actual behavior.
• SkillGuard itself is genuinely early: 1 GitHub star, about a month since the first commit. That's a real "early but real" story, not something worth dressing up: every command and finding shown in this README was run against the actual current code while writing it, not carried over from an old draft.

What is SkillGuard, and why does it exist

SkillGuard is a static-analysis scanner for third-party AI agent-skill files, SKILL.md manifests plus the hooks and scripts they bundle, built to run before an untrusted skill is installed or executed. It exists because agent-skill marketplaces and frameworks generally have no scan step of their own: a skill can declare network: false in its frontmatter and still ship a postinstall hook that pipes a remote script into a shell the moment it's installed, and nothing in most agent runtimes checks that the declared scope matches the actual behavior. SkillGuard reads the same ten rule packs from a CLI, a library, an MCP server, and a GitHub Action, so the same check can gate a CI pipeline, run inside an agent's own tool-use loop, or be called directly from code.

Suppressing findings

[!WARNING] SkillGuard's job is to vet directories you did not write. Both suppression mechanisms below can silence a finding, so neither is ever trusted automatically from inside the thing being scanned. Each requires an explicit, deliberate opt-in from whoever runs the scan.

A .skillguardignore file suppresses whole files by glob, same mental model as .gitignore:

# .skillguardignorevendor/***.generated.js

It is only honored when you pass --skillguardignore <path> (or the ignoreFilePath library option). SkillGuard never reads a .skillguardignore living inside the scan target on its own. A malicious skill submission that ships its own .skillguardignore cannot silence findings about itself unless you explicitly point SkillGuard at that file. If you maintain a skill yourself and want self-suppression, keep your .skillguardignore and pass its path explicitly:

npx skillguard-cli scan ./my-skill --skillguardignore ./my-skill/.skillguardignore

An inline # skillguard-ignore: SG02 comment (on the same line as the match, or the line directly above it) suppresses a single finding in place. This is off by default and requires --allow-inline-suppression, for the same reason: the comment lives inside the exact untrusted content being vetted, so by default nothing in a scan target can silence a finding about itself. Only enable it for a target you already trust, e.g. self-scanning your own skill before publishing.

Known limitations

SkillGuard documents its gaps in the open, on purpose. Two worth calling out here beyond SG05's false-negative note above: symlinked scan targets are left unscanned rather than followed, and the Python package's cross-skill detection currently lives only in scan-set, not as a single-skill sibling-path check the way TypeScript's does. The full list, including the residual single-pattern ReDoS risk, lives in CHANGELOG.md. Read it before wiring SkillGuard into a CI gate you plan to trust.

Development

# TypeScriptnpm installnpm run buildnpm test
# Pythoncd pythonpython3 -m venv .venv && source .venv/bin/activatepip install -e ".[dev,mcp]"pytest

See CONTRIBUTING.md: a rule-pack change must land in both rulepacks/ and python/src/skillguard/rulepacks/data/ with equivalent test coverage in both suites, since a rule that only exists in one language is a silent behavior gap between the two CLIs.

FAQ

What is SkillGuard, and what makes it different from a general-purpose security scanner? SkillGuard is a static-analysis scanner purpose-built for one threat model: third-party AI agent-skill files, SKILL.md manifests plus the hooks and scripts they bundle. It ships ten rule categories (SG01-SG10) targeting things generic scanners don't check for by default, frontmatter-declared scope versus actual behavior, install-time hook supply-chain risk, prompt injection embedded in a skill's own instructional text, and combined risk across multiple skills in the same directory. A general SAST tool like Semgrep can find some of the same code-level patterns, but it has no notion of a SKILL.md manifest or a cross-skill privilege relationship.

Does SkillGuard require an account or API token to run a scan? No. npx skillguard-cli scan <path> and pip install skillguard-cli && skillguard scan <path> both work with zero signup, zero token, and no network call at scan time.

What platforms and language runtimes does SkillGuard support? The npm package needs Node.js >=20 (per package.json's engines field) and has no native/compiled dependencies. The PyPI package needs Python >=3.9 for the base install, or >=3.10 if you install the optional mcp extra for MCP server mode (per pyproject.toml's requires-python and its mcp optional-dependency comment). Both are pure-language packages with no OS-specific build step, and the Python package's classifiers declare Operating System :: OS Independent.

What do SG08, SG09, and SG10 check, and can they run through the MCP server too? SG08 (HIGH) looks for prompt injection inside a skill's own instructional text, attempts to override the host agent's system prompt or hijack its tool routing, across 7 distinct rule IDs. SG09 (HIGH) is cross-skill privilege chaining: scan-set flags a HIGH finding when one skill in a directory has sensitive-filesystem-read capability and another has network-egress capability with no declared sandboxing between them; TypeScript's plain scan also runs a narrower sibling-path variant of the same check. SG10 (HIGH) is marketplace typosquatting: a skill's declared name sitting Levenshtein edit-distance 1-2 from a bundled list of 51 popular npm/PyPI package names. All three run through npx skillguard-cli mcp's scan_skill tool exactly as they do through the CLI, since the MCP server calls the same underlying scan logic.

Can an AI agent call SkillGuard directly, instead of shelling out to a CLI and parsing output? Yes. npx skillguard-cli mcp (or skillguard mcp on the Python side) starts a stdio MCP server exposing a scan_skill tool, so an orchestrator or coding agent can scan a downloaded skill as a normal tool call before installing or running it.

Does SkillGuard catch a skill that references another, more privileged skill? scan-set does: point it at a directory of skill subdirectories and it flags a HIGH finding when one skill has sensitive-filesystem-read capability and another has network-egress capability with no declared sandboxing between them. This is the specific gap Snyk Agent Scan's own issue tracker confirms their tool doesn't cover yet (single-file, non-recursive).

What's the difference between the npm package and the PyPI package? Both are independent, equally maintained ports reading the same rule-pack contract and producing matching findings against the same target; the PyPI package is a genuine Python implementation, not a wrapper around the Node binary. One current gap: TypeScript's scan command runs an extra sibling-path cross-skill heuristic that Python doesn't have yet (Python's cross-skill detection lives entirely in scan-set). If you rely on cross-skill detection from a single scan call rather than scan-set, that path is TypeScript-only today, run scan-set on the Python side instead to get equivalent coverage.

Does SkillGuard replace Semgrep or Snyk? No. Semgrep is a mature, general-purpose static-analysis engine across 30+ languages; Snyk covers dependency and code vulnerabilities broadly, and Snyk Agent Scan covers a wider set of agent-skill and MCP-config threats than SkillGuard does today. SkillGuard's job is narrower: the specific SKILL.md/hooks/frontmatter threat model, with zero auth and a cross-skill check neither of those tools currently ships.

Is SkillGuard production-ready? It's early: about a month old, pre-1.0, 1 GitHub star as of this writing. The test suite (157/157 TypeScript, 110/110 Python) passes on a clean install and every command in this README was independently re-run against the current code, but it hasn't been run against a large real-world corpus yet, so treat its false-positive/false-negative rate as unproven at scale rather than settled.

Can I use SkillGuard commercially, and does the license cost anything? Yes, and no. SkillGuard is Apache License 2.0 (see LICENSE), which permits commercial use, modification, and redistribution, including inside proprietary software, at no cost, provided you keep the copyright and license notice. Apache 2.0 also grants an explicit patent license from contributors, which plain MIT does not.

License

Apache 2.0, see LICENSE.