skill-guard

Security scanner wrapper for OpenCode skill installation.

When you install a skill from an untrusted source, you're effectively running arbitrary code. skill-guard runs NVIDIA SkillSpector before every install — static analysis that checks for 64+ vulnerability patterns (sensitive API calls, file operations, network access, deserialization risks) — and decides: auto-approve / ask the user / block.

Prerequisites

| Tool | Version | Install | |------|---------|---------| | Node.js | >= 18 | nodejs.org | | Python | >= 3.12 | python.org | | SkillSpector | latest | pip install git+https://github.com/NVIDIA/skillspector.git |

It is recommended to install SkillSpector inside a Python virtual environment to avoid dependency conflicts.

Install

npm install -g @bioperl/skill-guard

Or use it without installing:

npx @bioperl/skill-guard install <ref>

Windows users: If skill-guard is not recognized after installing, use npx @bioperl/skill-guard install <ref> instead. This does not require a global install.

Usage

# Install a skill with automatic security scan
skill-guard install superpowers@git+https://github.com/obra/superpowers.git

# Install from a local path
skill-guard install /path/to/local/skill

# Skip the scan (not recommended)
skill-guard install --force-skip-security some-skill

# Show help
skill-guard --help

Supported reference formats

| Format | Example | Behavior | |--------|---------|----------| | git+https | name@git+https://github.com/user/repo.git | git clone to temp dir | | Local path | /home/me/skills/my-skill | Copy to temp dir | | file:// | file:///home/me/skills/my-skill | Same as local path |

Score reference

| Score | Behavior | Can override? | |-------|----------|---------------| | 0–20 SAFE | Auto-approve, installs immediately | — | | 21–80 CAUTION | Shows report, asks for confirmation | Yes (y) | | 81–100 BLOCK | Blocks installation, shows report | — | | Scan error | Aborts with error message | Must fix environment first |

How it works

skill-guard install <ref>
  → parseSkillRef()      Detect git+https / local / file://
  → fetchToTemp()        Clone or copy to temp directory
  → runScan()            Invoke SkillSpector (static analysis)
  → Should warn/block?
     SAFE    → installFromTemp()    → Move to ~/.cache/opencode/packages/
     CAUTION → askUser()            → install or cancel
     BLOCK   → exit(1) with report

Configuration

Create a skillSecurity section in your opencode.jsonc:

{
  "skillSecurity": {
    "enabled": true
  }
}

• enabled: false disables scanning (equivalent to --force-skip-security)
• Defaults to true if omitted entirely

Integration with OpenCode

skill-guard works alongside OpenCode by:

1. Cloning the skill to ~/.cache/opencode/packages/<name>/
2. Registering it in your opencode.jsonc under the plugin array
3. Restart OpenCode to load the new skill

Related projects

• OpenCode — The AI coding assistant that uses skills
• SkillSpector — NVIDIA's skill security scanner
• Superpowers — Community skill collection

License

MIT