VirtualBox Skills Suite for Pi

A complete, self-contained suite of Pi Skills for managing VirtualBox hypervisors, provisioning virtual machines, configuring networking, managing snapshots, transferring appliances, and performing disk maintenance directly via native VBoxManage commands.

Included Skills

| Skill | Description | Usage Command | | :--- | :--- | :--- | | vbox-install | Install/upgrade VirtualBox & Extension Pack (brew, apt, dnf, winget), vboxusers group, macOS kext. | /skill:vbox-install | | vbox-vm | Provisioning (Catalog, OVA, ISO), CPU/RAM sizing, lifecycle control (start, stop, pause). | /skill:vbox-vm | | vbox-network | NAT Networks, Host-Only interfaces, DHCP servers, port forwards, and IP discovery. Uses progressive disclosure — see references/. | /skill:vbox-network | | vbox-snapshot | Safety pre-change snapshots, snapshot trees, rollbacks, and delta merging. | /skill:vbox-snapshot | | vbox-transfer | Full/linked clones, OVA exports/imports, VM relocation, and guest file transfer. | /skill:vbox-transfer | | vbox-maintenance | Inventory audits, unregistering stale VMs, removing orphaned VDIs, and compacting disk space. | /skill:vbox-maintenance |

Prerequisites

• VirtualBox 7.x installed with VBoxManage accessible in your PATH.
• Node.js v20.6+ (for running the optional image catalog fetcher scripts/vbox-catalog.js).

Installation & Usage in Pi

Option A: Install globally in Pi

Copy or symlink the package into your global Pi skills folder:

mkdir -p ~/.pi/agent/skills/virtualbox
cp -r skills/* ~/.pi/agent/skills/virtualbox/

Option B: Install via npm package

In any project:

npm install --save-dev @bryanjbelanger/virtualbox-skills

And add to .pi/settings.json:

{
  "skills": ["node_modules/@bryanjbelanger/virtualbox-skills"]
}

Progressive Disclosure

Skills are structured so only what a task needs enters the context window:

1. Always in context — each skill's name + description only (~350 chars each).
2. Loaded on trigger — the SKILL.md body: a decision table plus the commands that cover the common 80%.
3. Loaded only if followed — references/*.md, linked from SKILL.md and read only when the task actually hits that path.

vbox-network is the worked example:

skills/vbox-network/
├── SKILL.md                      # topology decision table + the 80% commands
└── references/
    ├── port-forwarding.md        # both rule syntaxes, deletion, UDP/IPv6, collisions
    ├── host-only-macos.md        # DHCP ranges, bridged, macOS kext approval
    └── troubleshooting.md        # no internet, host can't reach guest, stale leases

When a SKILL.md grows past ~150 lines, move the rarely-needed detail into references/ rather than splitting the skill — splitting adds a second description to the permanent system prompt to save tokens that were never being spent.

OS Catalog Helper Script

To list or download official OS images (Ubuntu, Debian, Fedora, Rocky, Kali, etc.) with automatic checksum verification and Vagrant box extraction:

# List catalog images
node scripts/vbox-catalog.js catalog

# Fetch an OS image (downloads to ~/VirtualBox VMs/ISOs/)
node scripts/vbox-catalog.js fetch ubuntu

License

MIT License