Home

Docs

SkillGuard scans agent skills and MCP servers before they run. Use this page for the first install, the first scan, review actions, and the policies that decide when runtime calls are allowed or blocked.

Commands Troubleshooting

Quick install

Install the plugin or CLI

Claude Code users should install the plugin from the marketplace. Codex users install the local CLI shim, then add the personal plugin entry.

/plugin marketplace add mannanj/skillguard /plugin install skillguard@skillguard /reload-plugins codex plugin add skillguard@personal

First scan

Build the first local verdict

Run a local scan once after installation. SkillGuard scans configured skills and MCP servers, records the result in the local cache, and lets the hook read that verdict quickly at runtime.

skillguard --target all --engines local skillguard --target all

Claude Code

Use the plugin skill

In Claude Code, run /skillguard:skillguard or ask Claude to use SkillGuard. The hook checks cached verdicts on skill and MCP calls before the tool runs.

If the CLI is not on PATH, the hook prints the setup command that installs the stable local shim.

Codex

Use the Codex plugin

Start a new Codex session after installation, then pick SkillGuard from /skills, type $skillguard, or ask Codex to use SkillGuard to review cached findings.

Non-interactive runs can still use the CLI directly for summaries, review, and scan commands.

Reference

Command reference

Command What it does
skillguard --target all Scan skills and MCP servers.
skillguard --target all --engines local Scan everything with the offline local engine.
skillguard --agent-summary Print the cached high-risk launch summary.
skillguard --review Review active findings and choose next actions.
skillguard --activity Show scan, override, and hook activity.
skillguard --install-agent-adapters . Write repo adapters for the supported agent harnesses.

MCP checks

MCP checks and enforcement modes

SkillGuard discovers configured MCP servers, materializes a redacted scan surface, and checks launch commands, endpoint metadata, env/header names, and optional model-facing tool descriptions.

Default: enforce

MCP policy defaults to enforce. It blocks unscanned servers and critical or high-risk verdicts.

Relax when needed

Use skillguard --set-mcp-policy warn when you want logging and warnings without runtime refusal.

Static MCP scans never launch servers. Live introspection is opt-in because it connects to or launches the server to read tool descriptions:

skillguard --target mcps --mcp-introspect --engines local,skillaudit

Review flow

Review, acknowledge, and mark false positives

Use skillguard --review to walk active findings from an agent session. Choose mark-fp only after reviewing benign documentation-like matches. Choose ack when you saw the risk and explicitly want runtime to allow it.

False-positive marks live in the local triage file and persist across rescans unless a new finding appears.

Cache

Cache and rescan behavior

Verdicts and history are stored under the local SkillGuard cache. Missing, corrupted, unreadable, or stale cache entries fail closed for skill calls.

When a scanned skill or MCP config changes, scan it again so the runtime hook can compare against a fresh verdict.

Engines

Local versus optional cloud engines

The local engine is offline and dependency-free. Optional cloud or third-party engines add coverage when enabled, but they may send scan content to those services.

Use --engines local when nothing should leave the machine.

Troubleshooting

Common failures

  • No cached scan: run skillguard --target all --engines local.
  • Changed since scan: rescan the changed skill or MCP config before retrying.
  • Expected MCP blocking: check SKILLGUARD_MCP_POLICY or run skillguard --set-mcp-policy enforce.
  • Review noise: inspect the file, then use mark-fp only for a real false positive.

Security

Security and privacy notes

SkillGuard reads skill files and MCP configuration. Static scans do not execute skill code or launch MCP servers. Secret values are read in memory for detection and are not written to scan surfaces, findings, cache, or history.

Report bypasses, cache poisoning, secret persistence, or scanner execution bugs privately through the GitHub security advisory flow.