How to use the VM Lab for macOS GUI Testing agent skill

What the vm-lab skill makes the agent do

An agent skill is a folder with instructions (a SKILL.md file, plus any supporting files) that an AI agent reads when a task matches the skill's description. This one covers macOS GUI testing in a Parallels VM. When a task needs a clean macOS guest to test GUI automation, TCC prompts, screenshot capture, clicking, typing, performance, or two-way validation of Peekaboo-like tools, the agent follows the skill's workflow.

The core idea is that the agent runs the tool under test inside the guest, then verifies the result from outside the guest using Parallels screenshots and host-side observations. The skill also tells the agent not to close apps it does not own.

• Discover VMs and check their status with prlctl.
• Run guest commands as the guest user, capture host-side screenshots, and compare image dimensions.
• Launch tests from a visible Ghostty terminal when Screen Recording permission is involved.
• Check each GUI action with two independent signals: the tool's own output and an external verifier.
• Record performance with /usr/bin/time -p using repeated cold and warm runs.

Install the vm-lab skill in Claude

You can install the skill for a single project or for your user account. Download the ZIP from the skill's page on this site and unzip it. The skill folder must end up in the skills directory that Claude Code reads.

For a personal install, unzip into ~/.claude/skills/. For a single project, unzip into the project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal install: place the skill folder in ~/.claude/skills/.
• Project install: place the skill folder in the project's .claude/skills/ folder.
• Claude apps: upload the ZIP under Settings → Capabilities → Skills.
• The skill's files are agents/openai.yaml, references/bootstrap-diagnostics.md, scripts/parallels_type.py and SKILL.md.

Check what you need before you start

The skill depends on a specific setup. Confirm each item before asking the agent to run a test, because the workflow fails without them. The examples in the skill use a VM named macOS Tahoe and a guest user account named steipete. Use your own VM name and account, and make sure the VM is one you own and have prepared for testing.

• Parallels Desktop on the host, with the prlctl command-line tool available.
• A macOS guest VM with a user account the skill refers to as steipete.
• Python 3 on the host to run scripts/parallels_type.py.
• Ghostty terminal installed in the guest. This is optional but recommended for Screen Recording attribution.
• A Peekaboo source checkout in the guest for the baseline steps.
• Optional: the 1Password CLI (op), only if secrets are needed, and only inside tmux as the skill's rules require.

Ask the agent for a VM test in plain language

You do not need special syntax. Describe the task and mention the VM, the tool, and what you want verified. The skill triggers when the task needs a clean macOS VM for GUI or permission testing. Be specific about the target so the agent knows which VM it is allowed to use.

Good requests name the VM, the behaviour under test, and the evidence you expect back. The agent will then pick the matching commands and verification steps from the skill.

• Test whether Peekaboo's screenshot command works in the macOS Tahoe VM and compare its size with a prlctl capture.
• Check the Screen Recording permission prompt for my screenshot tool in a clean macOS Tahoe guest.
• Type into a controlled text field in the guest and confirm the value with the accessibility result and a host screenshot.
• Run cold and warm timings of my macOS command-line tool inside the guest and keep the outputs in /tmp.

Run a basic workflow: discover, capture, verify

Start with discovery. List the VMs, then check the target's status and IP. Next, run a simple guest command as the guest user to confirm access. The skill runs guest commands through prlctl exec and wraps them in a login shell that sources ~/.zprofile when it exists.

For verification, take an independent host-side screenshot with prlctl capture and read its pixel dimensions with sips. The agent compares this with the tool-under-test output. For Screen Recording tests, the skill says to launch the command from Ghostty, not from prlctl exec, because headless execution can give unhelpful permission attribution.

• List all VMs: prlctl list --all
• Check status and IP for one VM: prlctl list --info "macOS Tahoe"
• Capture a host-side reference image and read its size with sips.

Handle macOS permissions and typing through Ghostty

When a test needs Screen Recording or Accessibility, the responsible process matters. If the first capture fails, open System Settings > Privacy & Security > Screen & System Audio Recording inside the guest, allow Ghostty, then rerun the capture from Ghostty. The skill notes that permissions status run through prlctl exec can still report Screen Recording as false after Ghostty is allowed, so validate with a real capture.

The preferred path is to write a small launcher script in the guest, open Ghostty, then type only a short path such as ./r into the visible terminal. Typing long commands is error-prone because Parallels key injection uses its own key-code table and can depend on keyboard layout.

• Open the Screen Recording pane in the guest with the open command shown in the skill.
• Link the launcher into the guest user's home folder, then type ./r with scripts/parallels_type.py.
• If keystrokes produce garbage, send Return to clear the line, create a shorter launcher, and retry.