<!-- mcp-name: ai.skilltotal/skilltotal -->

SkillTotal

AI Component Security Platform — open-source CLI engine.

SkillTotal statically analyzes AI-related components — agent skills/plugins, MCP servers, npm / Python packages, repositories, and AI-generated projects you upload as an archive or file — to surface supply-chain risks, dangerous capabilities, prompt-injection surfaces, and data-exfiltration paths before the component is installed or trusted. Point it at a path, a git URL, an npm: / pypi: package, or a project archive (.zip / .tar.gz) / single file.

Try it online (no install, no account): www.skilltotal.ai — the website runs this same engine. Prefer the CLI? pipx install skilltotal (below).

It analyzes only the component itself — never your user, company, environment, deployment, or runtime context. Every score and finding is derived exclusively from the files inside the component.

Core principle: every confirmed finding carries evidence (file, line range, code snippet). Anything that cannot be evidenced is placed in needs_review, never in findings, and never affects the score.

Why SkillTotal

• Checks packages before your agent installs them. The Claude Code plugin reads each npx, npm install, pip install or claude mcp add command the agent is about to run. It blocks packages with malicious indicators and asks you before installing high- or critical-risk ones. Set it up.
• 100% local & offline — the component's code never leaves your machine. No account, no API token, no cloud upload (unlike cloud scanners that send your components to a backend).
• Safe to point at untrusted components — the engine analyzes without ever running them on your machine. (Optional dynamic analysis is a separate paid service that runs only in our isolated sandbox, with your consent.)
• Zero runtime dependencies, pure Python stdlib — auditable and easy to vendor/air-gap.
• Deterministic — regex + AST, no LLM in the static engine; the same input always yields the same report.
• Evidence-anchored & low false-positive — every finding points at an exact file:line.
• Standards-aligned — every component gets a behavioral trait fingerprint mapped to the Cloud Security Alliance (CSA) agentic threat model, MAESTRO threat-model layers, and MITRE ATLAS tactics — including a three-way execution-context read (embedded static credential → delegated OAuth/OIDC → least-privilege scoped identity) that shows the blast radius of a compromise, not just that a secret exists.
• Free and open source (Apache-2.0) — the full static report is free, forever.

Measured, not asserted

Detection claims are cheap, so the numbers behind them are published with the data and the code that produced them.

• The whole MCP registry, scanned — every distinct component in the official registry, 17,535 of them, in one deterministic run. 88.2% expose tools to an agent, 64.8% can reach the network, 21.1% can execute shell commands — and the risk distribution underneath is far flatter, because a capability scores zero here. Raw JSON · the harness.
• Detection efficacy — recall and precision on a labelled corpus, regenerated every release and enforced by CI as a floor.

Every one of these reproduces: same input, same engine, same output. Nothing is executed and no LLM is involved.

Install

Requires Python 3.10+. Zero runtime dependencies. git is required only for scanning remote URLs.

Recommended for the CLI — pipx (isolated install; also works on Debian/Ubuntu where bare pip install is blocked by PEP 668):

pipx install skilltotal

Or into a virtual environment / as a library:

pip install skilltotal

You can also run it with npx. The npm package only starts this engine, so you need uv, pipx, or a Python with skilltotal installed:

npx -y skilltotal scan https://github.com/owner/repo

From source (development):

pip install -e ".[dev]"

Claude Code plugin

Coding agents install packages without asking you. The plugin checks each package before the install command runs, using the same engine on your machine. If a package has malicious indicators, the command is denied and the agent is told why. A high- or critical-risk package needs your approval, and so does a package from a custom registry or a direct archive URL, because SkillTotal can only scan the copy on the public registry. Clean packages install as usual.

The repository doubles as a plugin marketplace, so inside Claude Code run:

/plugin marketplace add pezhik/skilltotal
/plugin install skilltotal@skilltotal

Then run /reload-plugins or restart Claude Code. The hook loads along with the plugins, so until you do, it does not check install commands in the session where you ran /plugin install.

The plugin calls the CLI, so you also need pip install skilltotal (0.56.3 or later). If the CLI is missing or fails to start, install commands run unchecked and nothing is blocked. Claude Code shows a warning on each one, so you can tell a broken setup from a clean check.

Install the CLI where Claude Code can find it: skilltotal --version should work in the terminal you start Claude Code from. To see the hook work without touching a real package, ask the agent to run npm install --registry https://registry.example.invalid left-pad. Claude Code should stop and ask you, with SkillTotal's reason. Nothing is installed unless you approve.

On Windows, Claude Code runs most commands through its PowerShell tool. Before each command the agent runs through the Bash or PowerShell tool, a hook looks for packages the command would install: npx, bunx, pnpm dlx, npm/pnpm/yarn/bun add or install, pip, uv, uvx, pipx, and claude mcp add … -- <command>. Other commands pass straight through. If a package has malicious indicators, the command is denied and the agent sees why. A high- or critical-risk package needs your approval. A clean one installs as usual, and the agent gets a one-line note with its score.

A package from a custom registry or index (--registry, --index-url, --extra-index-url) or a direct archive URL always needs your approval, because SkillTotal can only scan the copy on the public registry, and that may not be the one that gets installed. Packages from GitHub (github:owner/repo, git+https://github.com/...) are scanned from the repository.

All checks for one command share a 20-second budget (set SKILLTOTAL_HOOK_BUDGET to change it). A package that isn't checked in time, or whose check fails, never blocks the install, and the agent is told it wasn't checked. Verdicts are reused for 24 hours and redone when the engine version changes, so repeated npx tsc or npx prettier calls don't trigger a rescan. The plugin also adds a /skilltotal:scan <target> command and registers the MCP server described below.

The hook reads a command the way the shell would, through sudo, env, bash -c '...', cmd /c, $(...), groups like (npm i y) and chains like cd x && npm i y. For PowerShell it also follows & { ... }, iex '...', Start-Process npm -ArgumentList ... and powershell -EncodedCommand. It only sees what the command spells out, so a command that builds the package name at run time, or a script the agent downloads and runs, gets past it. For code you don't trust, run the agent in a container.

Usage

# Human-readable report
skilltotal scan ./path/to/component

# Scan a remote repository (shallow git clone)
skilltotal scan https://github.com/owner/repo

# Scan a project archive or a single file (e.g. an AI-generated project downloaded as a ZIP)
skilltotal scan ./my-project.zip
skilltotal scan ./app.tar.gz
skilltotal scan ./suspicious.py

# Scan a package from a registry (latest, or a pinned version)
skilltotal scan npm:left-pad
skilltotal scan npm:left-pad@1.3.0
skilltotal scan pypi:requests
skilltotal scan pypi:requests==2.31.0

# JSON to stdout
skilltotal scan ./component --json

# SARIF 2.1.0 (GitHub Code Scanning / IDE)
skilltotal scan ./component --sarif --output report.sarif

# Write the report to a file (SARIF if --sarif, else JSON)
skilltotal scan ./component --output report.json

# CI gate: exit code 2 by severity level or by risk score
skilltotal scan ./component --fail-on-high             # alias for --fail-on high
skilltotal scan ./component --fail-on medium
skilltotal scan ./component --fail-on-score 50

# Skip paths (repeatable; combined with the config file's `exclude`)
skilltotal scan ./component --exclude "vendor/*" --exclude "*.min.js"

# Opt-in provenance for npm:/pypi: sources (registry metadata -> needs_review, never scored)
skilltotal scan npm:some-lib --provenance

# Baseline: snapshot current findings, then suppress them on later scans
skilltotal scan ./component --write-baseline .skilltotal-baseline.json
skilltotal scan ./component --baseline .skilltotal-baseline.json --fail-on-high

# Diff two versions of a component: what changed between them?
# Each side is any scannable source (path/archive/git/npm:/pypi:) or a saved --json report.
skilltotal diff npm:some-lib@1.2.3 npm:some-lib@1.2.4
skilltotal diff ./old-checkout ./new-checkout --json
skilltotal diff old-report.json new-report.json
# CI gate: fail (exit 2) if the new version INTRODUCES a high/critical finding
skilltotal diff npm:some-lib@1.2.3 npm:some-lib@1.2.4 --fail-on-new high

# Pre-install guard: allow/block decision (exit 2 on block) you can chain before installing
skilltotal guard npm:some-mcp-server && claude mcp add some-mcp-server -- npx some-mcp-server
skilltotal guard --installed            # check every AI component already on this machine
skilltotal guard npm:x --block-on malicious   # block only on malicious indicators

# Inventory: discover AI components already installed on this machine and scan them
# (reads agent configs for Claude Desktop/Code, Cursor, Windsurf, VS Code, Gemini, and
#  local skills; derives an npm:/pypi:/local source per MCP server and runs the engine)
skilltotal inventory
skilltotal inventory --json
skilltotal inventory --no-scan          # list only, do not scan
skilltotal inventory --project .        # also include this project's agent configs
skilltotal inventory --sbom             # AI-BOM: CycloneDX 1.6 JSON of your agent stack,
                                        # scan verdicts attached as component properties

# List every detection rule
skilltotal rules list
skilltotal rules list --json

Baseline suppresses findings by a stable fingerprint of (rule id, file, code snippet) — independent of line numbers, so it survives edits. Suppressed findings are removed before scoring and do not affect the risk score.

Diff reports new / resolved / changed findings, evidence-level additions and removals (matched by the same line-independent fingerprint as the baseline, so pure line shifts are not noise), capa