New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Parallels macOS VM Lab

by steipete in steipete/agent-scripts

Uses a clean Parallels macOS VM to test GUI automation, TCC permission prompts and screenshot tools like Peekaboo, verifying results from outside the guest.

MITAuto-check passedTesting & QA

Install Parallels macOS VM Lab

skills CLI
$ npx skills add steipete/agent-scripts --skill vm-lab -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install steipete/agent-scripts vm-lab --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/steipete/agent-scripts.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/vm-lab .claude/skills/vm-lab && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
vm-lab
GitHub stars
7.3k
Token cost
~1.8k tokens
SKILL.md length
771 words
Files
4 (incl. scripts, references)
Skills in repo
45
Repo updated
First seen
Licence
MIT

At a glance

Uses a clean Parallels macOS VM to test GUI automation, TCC permission prompts and screenshot tools like Peekaboo, verifying results from outside the guest.

  • Testing a GUI automation tool on a clean macOS VM
  • SKILL.md covers Safety Rules, Bootstrap Preflight, VM Discovery and TCC / GUI Attribution, plus 5 more sections
  • Runs Python scripts from its folder; calls swift, python3 and git
  • Debugging Screen Recording or Accessibility prompts for a tool

What it does

The core idea is to run the tool under test inside the guest VM while checking it from the host with Parallels screenshots and other host-side observations, a two-way validation. Safety rules apply throughout: only task-owned clones are disposable, source and golden snapshots and other tasks' VMs are never reset or deleted, inherited guest credentials are never used, secrets are never printed, and host writes stay limited to temporary diagnostics.

Practical sections cover a bootstrap preflight (confirm the exact VM UUID and snapshot provenance, and diagnose clones that fail to boot or packaging that hangs), VM discovery with prlctl list, running guest commands with prlctl exec, capturing host-side screenshots with prlctl capture, and attributing macOS Screen Recording and Accessibility permissions to the responsible process. A parallels_type.py script and a bootstrap-diagnostics reference are included, and fresh windows such as TextEdit or a local HTML page are preferred as test targets.

When your agent uses it

  • Testing a GUI automation tool on a clean macOS VM
  • Debugging Screen Recording or Accessibility prompts for a tool
  • Capturing independent screenshots of a guest VM from the host

Example prompts

  • “Set up a task-owned clone of the macOS VM and test Peekaboo clicking in TextEdit.”
  • “List my Parallels VMs and show the status of the macOS one.”
  • “The guest's screen capture permission keeps prompting. Use the VM lab to find out why.”

Requirements

  • Parallels Desktop with the prlctl command
  • A macOS guest VM

What it can do on your machine

Read from SKILL.md and the folder at commit 79150cf. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • swift
    • python3
    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Parallels macOS VM Lab loads about 1.8k tokens when it runs, and up to ~4.6k if it reads all its reference files. Until then it costs about 18 tokens; SKILL.md has 771 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~18
When it runs · the whole SKILL.md, loaded when a task matches
~1.8k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~4.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from steipete/agent-scripts at commit 79150cf, republished under its MIT licence (© steipete). 771 words, ~1,828 tokens.

Download SKILL.mdSave it as .claude/skills/vm-lab/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.
name
vm-lab
description
Parallels macOS VM lab: GUI automation, Peekaboo, TCC, Ghostty.

VM Lab

Use this when the task needs a clean macOS VM to test GUI automation, TCC prompts, screenshot capture, clicking, typing, performance, or "two-way validation" of Peekaboo-like tools.

Core idea: run the tool under test inside the guest, but verify it from outside the guest with Parallels screenshots and host-side observations. Do not close apps you do not own.

Safety Rules

  • Only task-owned clones are disposable. Preserve source/golden snapshots, recovery VMs, and other tasks' VMs; never reset, revert, or delete their snapshots.
  • Never access inherited guest credentials or bypass login/startup security to bootstrap a clone.
  • Never print secrets. If op is needed, follow the 1Password skill and run it only inside tmux.
  • Prefer fresh app windows you create yourself: TextEdit, a local HTML test page, or a small test app.
  • Limit host writes to task-owned temporary diagnostics and explicitly authorized clone recovery. Never change global Bash/Codex settings for a lab workaround.
  • For git repos inside the VM, use HTTPS remotes and normal branch discipline.

Bootstrap Preflight

Before guest automation, confirm the exact task-owned VM UUID and snapshot provenance; the names below are examples, not permission to operate an existing VM.

  • Apple-VZ clone fails to boot: verify the active raw disk's contents, not just clone success or logical size. A sparse linked child alone does not prove a broken chain; clone --unlink creates another clone, not an in-place repair.
  • Packaging hangs before its first output: inspect the task-owned shell process and heredoc redirection before changing product code or build guards. A system-Bash retry must also pin PATH-resolved child shells, for that invocation only.

Use Bootstrap diagnostics for read-only checks, evidence limits, and narrowly scoped recovery boundaries.

VM Discovery

List VMs:

bash
prlctl list --all

Get VM status/IP:

bash
prlctl list --info "macOS Tahoe"

Run guest commands as Peter:

bash
prlctl exec "macOS Tahoe" \
  'sudo -u steipete -H /bin/zsh -lc '\''source ~/.zprofile 2>/dev/null || true; uname -a'\'''

Capture an independent host-side screenshot:

bash
prlctl capture "macOS Tahoe" --file /tmp/vm-reference.png
sips -g pixelWidth -g pixelHeight /tmp/vm-reference.png

TCC / GUI Attribution

For macOS Screen Recording and Accessibility, the responsible process matters.

  • prlctl exec is headless and can fail to produce useful Screen Recording attribution.
  • Launch the test command from a visible terminal app in the guest when Screen Recording is involved.
  • Ghostty works as a GUI terminal if installed.
  • After a first failed capture, check System Settings > Privacy & Security > Screen & System Audio Recording.
  • permissions status run through prlctl exec may still report Screen Recording false after Ghostty is allowed; validate Screen Recording by rerunning the capture from Ghostty.

Open the Screen Recording pane:

bash
prlctl exec "macOS Tahoe" \
  'sudo -u steipete -H open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"'

Open Ghostty:

bash
prlctl exec "macOS Tahoe" 'sudo -u steipete -H open -a Ghostty'

Running Commands Through Ghostty

Best path: create a guest script with prlctl exec, open/focus Ghostty, then type only a short launcher path into the visible terminal.

Guest script pattern:

bash
prlctl exec "macOS Tahoe" 'sudo -u steipete -H /bin/zsh -lc '\''cat > /tmp/run-vm-lab.zsh <<EOF
#!/bin/zsh
source ~/.zprofile 2>/dev/null || true
cd ~/Projects/Peekaboo || exit 1
Apps/CLI/.build/debug/peekaboo image --path /tmp/peekaboo-vm.png --json
rc=$?
echo "EXIT:$rc"
[ -f /tmp/peekaboo-vm.png ] && sips -g pixelWidth -g pixelHeight /tmp/peekaboo-vm.png
echo "Press return to close..."
read _
exit $rc
EOF
chmod +x /tmp/run-vm-lab.zsh
ln -sf /tmp/run-vm-lab.zsh /tmp/r
open -a Ghostty'\'''

Then link the launcher into Ghostty's home directory and type ./r with scripts/parallels_type.py. This avoids unreliable path characters in Parallels key injection.

bash
prlctl exec "macOS Tahoe" \
  "sudo -u steipete -H /bin/zsh -lc 'ln -sf /tmp/run-vm-lab.zsh ~/r'"
python3 skills/vm-lab/scripts/parallels_type.py "macOS Tahoe" $'./r\n'

Avoid long command typing. Parallels key injection uses its own key-code table and can be layout-sensitive.

Show full SKILL.md (314 more words)Show less

Known Pitfalls

  • macOS clipboard APIs may fail from prlctl exec; pbcopy, AppleScript clipboard, and Peekaboo paste can all fail in headless guest context.
  • open -na Ghostty.app --args -e ... may only focus an existing Ghostty window on macOS; do not assume it runs the command.
  • prlctl exec may re-join argv through a guest shell; for complex payloads, pass one fully shell-quoted command string or create the file with a tiny Python writer.
  • Parallels send-key-event --key uses Parallels key values, not macOS virtual key codes.
  • For normal typing, send prlctl send-key-event <vm> --key <key> with no --event; explicit press/release can repeat or stick. Return is an exception: use press then release.
  • Prefer one prlctl send-key-event --json batch over many separate send-key-event processes; separate calls can drift under focus/latency.
  • Use PRL_KEY_ENTER = 36, PRL_KEY_SLASH = 61, PRL_KEY_R = 27, PRL_KEY_T = 28, PRL_KEY_M = 58, PRL_KEY_P = 33.
  • If keystrokes produce garbage, send Return to clear the line, create a shorter launcher, then retry.
  • If Peekaboo permission probes hang with Screen Recording missing and emit SWIFT TASK CONTINUATION MISUSE, record it as a product bug; do not confuse it with the VM harness.

Two-Way Validation

For each GUI action, verify through two independent signals:

  • Tool-under-test output: JSON, screenshot file, AX result, or app state.
  • External verifier: prlctl capture, host-side image inspection, file content in guest, or process/window state.

Examples:

  • Screenshot: compare Peekaboo image dimensions/content against prlctl capture.
  • Click: use Peekaboo to click a test button, then verify both guest app state and host screenshot.
  • Type: use Peekaboo to type into a controlled text field, then verify AX value and host screenshot.
  • Performance: wrap commands with /usr/bin/time -p; repeat cold/warm runs; keep outputs in /tmp.

Peekaboo VM Baseline

Inside guest:

bash
cd ~/Projects/Peekaboo
git pull --recurse-submodules
swift build --package-path Apps/CLI
Apps/CLI/.build/debug/peekaboo --version
Apps/CLI/.build/debug/peekaboo permissions status --json

Host-side reference capture:

bash
prlctl capture "macOS Tahoe" --file /tmp/vm-prlctl-reference.png

Guest-side Peekaboo capture through Ghostty:

bash
/tmp/r

Compare:

bash
prlctl exec "macOS Tahoe" \
  'sudo -u steipete -H /bin/zsh -lc '\''sips -g pixelWidth -g pixelHeight /tmp/peekaboo-vm.png'\'''
sips -g pixelWidth -g pixelHeight /tmp/vm-prlctl-reference.png

Reporting

When handing off, include only:

  • VM name and OS build.
  • repo commit tested.
  • permission state.
  • commands that passed/failed.
  • independent verifier result.
  • product bugs discovered.

© steipete, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (scripts, references) in skills/vm-lab of steipete/agent-scripts.

  • SKILL.md
  • agents/openai.yaml
  • references/bootstrap-diagnostics.md
  • scripts/parallels_type.py

Open the folder on GitHubat commit 79150cf

Compare with similar skills

Parallels macOS VM Lab next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Parallels macOS VM Lab compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Parallels macOS VM Lab this skillsteipete/agent-scripts7.3k—~1.8kAutomated safety check: PassMIT
Stevemikker/steve170—~421Automated safety check: PassNone
Evidence-Driven Testingmichaelshimeles/skills1.3k1 repos~3.9kAutomated safety check: PassNone
Electron App Screenshotkeybase/client9.3k—~476Automated safety check: PassBSD-3-Clause
Warp UI Testing with Computer Usewarpdotdev/warp65k1 repos~1kAutomated safety check: PassAGPL-3.0
Bot Channel Acceptance Testinglobehub/lobehub83k—~1kAutomated safety check: PassCustom licence

Similar skills

  • Steve

    mikker/steve

    Use the steve CLI to automate macOS apps via Accessibility APIs.

    170 GitHub stars~421 tokensUpdated 6 mo ago
    Testing & QAAuto-check passed

  • Evidence-Driven Testing

    michaelshimeles/skills

    Records an annotated screen recording of the agent testing an app hands-on, then posts the video and a results summary to the PR and tracker issue.

    1.3k GitHub starsUsed in 1 repo~3.9k tokens
    Testing & QAAuto-check passed

  • Electron App Screenshot

    keybase/client

    Takes a screenshot of a running Electron desktop app through playwright-cli over remote debugging, shrinks it and shows it so you can check the UI visually.

    9.3k GitHub stars~476 tokensUpdated today
    Testing & QAAuto-check passed

  • Warp UI Testing with Computer Use

    warpdotdev/warp

    Guides visual testing of Warp UI changes by launching the app with an API key and driving it through the computer use tool, with optional mocked state.

    65k GitHub starsUsed in 1 repo~1k tokens
    Testing & QAAuto-check passed

  • Bot Channel Acceptance Testing

    lobehub/lobehub

    Extends a project's acceptance process to real chat bot channels: Discord, Slack, Telegram, WeChat, Lark, QQ, and iMessage on macOS.

    83k GitHub stars~1k tokensUpdated today
    Testing & QAAuto-check passed

  • Cloud UI Change Verification

    warpdotdev/warp

    Verifies a Warp client change by pushing it to a branch and spawning a cloud agent with computer use that follows the test-warp-ui skill, only when you ask for it.

    65k GitHub stars~1.2k tokensUpdated today
    Testing & QAAuto-check passed

More from steipete/agent-scripts

All 45 skills in this repo

  • Mac Fleet Maintenance

    steipete/agent-scripts

    Inventories and maintains a fleet of Macs from a desired-state file: package updates, repo and Xcode sync, and disk, backup and security health reports.

    7.3k GitHub stars~4.8k tokensUpdated 3 days ago
    Auto-check passed

  • Agent Transcript for PRs

    steipete/agent-scripts

    Finds a coding agent's session log, trims and redacts it, and inserts it into a GitHub PR or issue only when the user has asked for a transcript.

    7.3k GitHub starsUsed in 1 repo~698 tokens
    Auto-check passed

  • ClawSweeper Status

    steipete/agent-scripts

    Reports ClawSweeper's status with a bundled script: workflow health, active workers, queue health and recently merged, reviewed, commented and closed items.

    7.3k GitHub stars~972 tokensUpdated 3 days ago
    Auto-check passed

  • GitHub Project Triage

    steipete/agent-scripts

    Produces maintainer-facing triage cards for a project's GitHub issues and pull requests, each with its URL, risk, test state, blockers and a next action.

    7.3k GitHub stars~4k tokensUpdated 3 days ago
    Auto-check passed

  • Nano Banana Image Generation

    steipete/agent-scripts

    Generates and edits images with Google's Nano Banana 2 (Gemini 3.1 Flash Image) through a uv script, with a draft-then-final workflow and sizes from 512 to 4K.

    7.3k GitHub stars~1.4k tokensUpdated 3 days ago
    Auto-check passed

  • npm Registry Operations

    steipete/agent-scripts

    Handles npm registry tasks such as whoami checks, package name availability, name reservation and publishing, with credentials pulled from 1Password.

    7.3k GitHub stars~1.1k tokensUpdated 3 days ago
    Auto-check passed

Works with

Categories

Questions about Parallels macOS VM Lab

What does Parallels macOS VM Lab do?

Uses a clean Parallels macOS VM to test GUI automation, TCC permission prompts and screenshot tools like Peekaboo, verifying results from outside the guest. The core idea is to run the tool under test inside the guest VM while checking it from the host with Parallels screenshots and other host-side observations, a two-way validation. Safety rules apply throughout: only task-owned clones are disposable, source and golden snapshots and other tasks' VMs are never reset or deleted, inherited guest credentials are never used, secrets are never printed, and host writes stay limited to temporary diagnostics.

When should I use Parallels macOS VM Lab?

Parallels macOS VM Lab fits situations like: testing a GUI automation tool on a clean macOS VM; debugging Screen Recording or Accessibility prompts for a tool; capturing independent screenshots of a guest VM from the host.

How do I install Parallels macOS VM Lab in Claude Code?

Run `npx skills add steipete/agent-scripts --skill vm-lab -a claude-code`. Or copy the skill folder (skills/vm-lab in steipete/agent-scripts) into .claude/skills/vm-lab in your project. Claude Code loads it when a task matches its description.

How do I install Parallels macOS VM Lab in Codex?

Run `npx skills add steipete/agent-scripts --skill vm-lab -a codex`. Or copy the skill folder (skills/vm-lab in steipete/agent-scripts) into .agents/skills/vm-lab in your project. Codex loads it when a task matches its description.

Can I use Parallels macOS VM Lab in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add steipete/agent-scripts --skill vm-lab -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/vm-lab, .gemini/skills/vm-lab, .github/skills/vm-lab and .opencode/skills/vm-lab in your project.

What does Parallels macOS VM Lab need to run?

Going by SKILL.md and its folder, Parallels macOS VM Lab needs Python for the scripts in its folder and the command-line tools its instructions call (swift, python3 and git). Our summary lists: Parallels Desktop with the prlctl command; A macOS guest VM.

Does Parallels macOS VM Lab access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Parallels macOS VM Lab safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Parallels macOS VM Lab use?

Parallels macOS VM Lab is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Parallels macOS VM Lab use?

About 1.8k tokens (SKILL.md is roughly 7.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 2.7k tokens, read only when the agent opens those files.

What are the alternatives to Parallels macOS VM Lab?

Skills that share tags, products or a category with Parallels macOS VM Lab: Steve (mikker/steve, 170 stars), Evidence-Driven Testing (michaelshimeles/skills, 1.3k stars), Electron App Screenshot (keybase/client, 9.3k stars) and Warp UI Testing with Computer Use (warpdotdev/warp, 65k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Parallels macOS VM Lab?

steipete (a GitHub user) maintains it in steipete/agent-scripts, which has 7,273 GitHub stars. The repository holds 45 skills in this directory. The repository was last updated on October 4, 2026.

Source: steipete/agent-scripts on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.