skillguard

<div align="center"> # SkillGuard Scans third-party AI agent-skill files (`SKILL.md` manifests, hooks, and bundled scripts) for known attack patterns before they run, and is the only scanner in its category you can also call as an MCP tool from inside another agent. [](https://github.com/RudrenduPaul/skillguard/actions/workflows/ci.yml) [](https://www.npmjs.com/package/skillguard-cli) [](https://pypi.org/project/skillguard-cli/) [](./LICENSE) [](./CHANGELOG.md) </div>  ## 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](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/) 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. ## Install ```bash # 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 ```bash 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. Every scan prints "Loading SkillGuard rule packs..." to stderr first; that's expected, not a hang. Compare it against a clean fixture: ```bash npx skillguard-cli scan ./examples/clean-skill ``` which returns zero findings and exit code 0. ## Table of contents - [Why this exists](#why-this-exists) - [Install](#install) - [Try it now](#try-it-now) - [Features](#features) - [Quickstart](#quickstart) - [Commands](#commands) - [API reference](#api-reference) - [MCP server](#mcp-server-agent-native-tool-call) - [GitHub Action](#github-action) - [Rule packs](#rule-packs) - [How SkillGuard compares](#how-skillguard-compares) - [What is SkillGuard, and why does it exist](#what-is-skillguard-and-why-does-it-exist) - [Suppressing findings](#suppressing-findings) - [Known limitations](#known-limitations) - [Development](#development) - [FAQ](#faq) - [License](#license) ## 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](./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](https://github.com/snyk/agent-scan/issues/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 ```bash npx skillguard-cli scan ./my-skill --format json --severity-threshold MEDIUM ``` ```ts 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`); } ``` ```python 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 ```bash npx skillguard-cli <command> [options] # Python: skillguard <command> [options] ``` | Command | What it does | | --- | --- | | `scan <path>` | Scans one skill directory (a `SKILL.md` plus its hooks/scripts) for known attack patterns. | | `scan-set <dir>` | Scans a directory whose immediate children are each a skill directory, running `scan` on every one and additionally checking for cross-skill privilege chaining (SG09) across the set. | | `mcp` | Starts SkillGuard as a stdio MCP server, exposing `scan_skill` as a callable tool for another agent. See [MCP server](#mcp-server-agent-native-tool-call). |  Flags shared by `scan` and `scan-set` (verified against `src/cli.ts` and `skillguard/cli.py`): | Flag | Default | Description | | --- | --- | --- | | `--format <human\|json\|sarif>` | `human` | Output format. | | `--severity-threshold <HIGH\|MEDIUM\|LOW>` | `HIGH` | Minimum severity that fails the scan (exit code 1). | | `--timeout <ms>` | `10000` | Per-file scan timeout in milliseconds. | | `--skillguardignore <path>` | none, must be passed explicitly | Path to a suppression file. Never auto-loaded from inside the scan target; see [Suppressing findings](#suppressing-findings). | | `--allow-inline-suppression` | `false` | Honor inline `# skillguard-ignore: SGxx` comments found inside the scanned files. Off by default. | **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: ```ts 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`): ```python 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) ```bash 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: ```json { "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](./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). ## GitHub Action ```yaml - 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](./CONTRIBUTING.md)'s parity rule. Nothing is fetched over the network at scan time. | Category | Name | Severity | What it catches | | --- | --- | --- | --- | | SG01 | network mismatch | MEDIUM | Raw sockets, netcat, `/dev/tcp`, network primitives that bypass a typical HTTP-only scope. | | SG02 | remote code execution | HIGH | `curl \| bash`, `eval()`/`exec()` of a fetched response, shelling out with remote-influenced content. | | SG03 | file-scope escalation | MEDIUM | Writes/deletes/`chmod` reaching outside the skill's own directory, and path traversal (`../../..`) used to escape it. | | SG04 | hook supply-chain | HIGH | Install-time hooks or dependencies that fetch and run remote code, or pin to a mutable branch. | | SG05 | obfuscated payloads | LOW | base64/string-concat/dynamic-`Function` idioms used to hide a payload. See the known limitation below. | | SG06 | credential harvesting | HIGH | Reads of credential-shaped env vars or credential files, especially near a network call. | | SG07 | frontmatter spoofing | MEDIUM | SKILL.md's declared network/filesystem scope vs. what the hooks/scripts actually do. | | SG08 | prompt injection via skill content | HIGH | SKILL.md's own instructional text trying to override the host agent's system prompt or hijack its tool routing (7 rule IDs: `sg08-ignore-prior-instructions`, `sg08-disregard-system-prompt`, `sg08-fake-mode-switch`, `sg08-reveal-system-prompt`, `sg08-hide-action-from-user`, `sg08-hidden-unicode-characters`, `sg08-encoded-block-in-instructions`). | | SG09 | cross-skill privilege chaining | HIGH | Combined capability across two skills in a `scan-set` run, one with sensitive-filesystem-read, one with network-egress, neither sandboxed from the other. TypeScript also runs a narrower single-skill sibling-path variant of this check; Python currently ships only the `scan-set` version. | | SG10 | marketplace typosquatting | HIGH | SKILL.md's declared name sitting Levenshtein edit-distance 1-2 from a bundled list of 51 popular npm/PyPI package names, an attempt to impersonate a well-known tool. | **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. | | SkillGuard | Snyk Agent Scan | Semgrep (CE) | Socket CLI | | --- | --- | --- | --- | --- | | What it scans | Agent-skill files: SKILL.md, hooks, scripts | Agent skills and MCP server configs | General source code, 30+ languages | npm/PyPI/etc. package installs | | Agent-skill-specific ruleset | Yes, all 10 categories purpose-built for this threat model | Yes, its whole focus (prompt injection, tool poisoning, toxic flows, skill malware) | No, general SAST rules only | No, supply-chain focused, not skill-file focused | | Scans multiple skills together for combined risk | Yes, `scan-set` (SG09 cross-skill privilege chaining) | No, confirmed single-file/non-recursive per [issue #301](https://github.com/snyk/agent-scan/issues/301) | Not applicable to this threat model | Not applicable to this threat model | | Callable as an MCP tool from another agent | Yes, `skillguard-cli mcp` | Not publicly documented | No | No | | Auth required for a basic scan | None (`npx skillguard-cli scan <path>`) | Yes, requires a Snyk account and `SNYK_TOKEN` | None for Community Edition local scans | Yes, `SOCKET_CLI_API_TOKEN` needed for full functionality | | Runtime | Node.js, zero external binary (Python port also available) | Python via `uvx` | Own binary (Python-based CLI) | Node.js | | License | Apache 2.0 | Apache 2.0 | LGPL-2.1 | MIT (per the [`socket` npm package listing](https://www.npmjs.com/package/socket); the repo itself carries no LICENSE file) | | GitHub stars (checked 2026-07-18) | 0, one week old, launched 2026-07-11 | 2,790 stars, 250 forks | 15,945 stars, 992 forks | 299 stars, 54 forks | 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,790 stars vs. SkillGuard's 0) 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**: zero GitHub stars, one week 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 **Trust model:** 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`: ``` # .skillguardignore vendor/** *.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: ```bash 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](./CHANGELOG.md). Read it before wiring SkillGuard into a CI gate you plan to trust. ## Development ```bash # TypeScript npm install npm run build npm test # Python cd python python3 -m venv .venv && source .venv/bin/activate pip install -e ".[dev,mcp]" pytest ``` See [CONTRIBUTING.md](./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: one week old, pre-1.0, zero GitHub stars 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](./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](./LICENSE).