Complete skill & reference for AI agents to run ANY Windows software on macOS — Not just Wine! Supports CrossOver, Whisky, Kegworks, Wineskin, Bottles, Game Porting Toolkit, and all Wine-based compatibility layers.
This repository provides a complete knowledge base and skill set for AI agents (Cursor, Claude Code, Codex, GitHub Copilot, Windsurf, etc.) to diagnose and solve problems when running Windows games, applications, and software on macOS through any Wine-based compatibility layer.
| Tool | Type | Best For | AI Agent Support |
|---|---|---|---|
| CrossOver (CodeWeavers) | Paid GUI + CLI | Non-technical users, one-click installs, official support | ✅ Full CLI via CX_BOTTLE |
| Wine (vanilla) | Free CLI (Homebrew/MacPorts) | Power users, max control, automation | ✅ Native wine, winecfg, winetricks |
| Whisky | Free GUI (Apple Silicon-first) | Gaming on M-series Macs, Game Porting Toolkit | ✅ Bottles are real Wine prefixes |
| Kegworks / Wineskin | Free wrapper builder | Distributing single apps as native .app bundles | ✅ Prefix accessible via WINEPREFIX |
| Bottles (Linux/Flatpak) | Free GUI | Cross-platform prefix management | ✅ Standard Wine prefix structure |
| Game Porting Toolkit (GPTK) | Apple's dev toolkit | Direct3D→Metal translation, game porting | ✅ Underlies Whisky/CrossOver |
| Document | Description |
|---|---|
| SKILL.md | Main skill for AI agents — Complete workflow, decision tree, and troubleshooting logic |
| references/tools-overview.md | Detailed comparison of all Wine-based tools on macOS |
| references/configuration.md | Windows version selection, DLL overrides, registry tweaks, DXVK/vkd3d |
| references/debugging-and-logs.md | Debugging workflows, log analysis (WINEDEBUG), common error patterns |
| references/cli-reference.md | Complete CLI reference: wine, winecfg, winetricks, CrossOver CLI, wineserver |
| references/common-fixes.md | Database of common issues: missing DLLs, black screens, audio, controllers, anti-cheat |
If you're an AI agent (Cursor, Claude Code, Codex, GitHub Copilot, Windsurf, etc.), load this skill:
The skill is defined in SKILL.md — it contains the complete workflow
for diagnosing and fixing Windows-on-macOS issues across ALL tools.
Key capabilities this skill gives AI agents:
- Identify which tool the user has (CrossOver, Wine, Whisky, Kegworks, etc.)
- Locate the correct bottle/prefix automatically
- Check WineHQ AppDB / CrossOver Compatibility for known recipes
- Apply correct Windows version, DLL overrides, DXVK/vkd3d settings
- Read and interpret
WINEDEBUGlogs (+loaddll,+seh,+module) - Fix missing DLLs via
winetricks(d3dx9, vcrun2019, dotnet48, dxvk) - Diagnose black screens, crashes, audio issues, controller problems
- Identify hard blockers (kernel anti-cheat, unsupported DRM, DX12 gaps)
- Identify your tool — Check tools-overview.md
- Find your bottle/prefix — See configuration.md
- Check compatibility — Search WineHQ AppDB or CrossOver Compatibility
- Follow debugging guide — See debugging-and-logs.md
- Check common fixes — See common-fixes.md
Every Wine-based tool creates a Wine prefix — a fake C:\ drive that's just a directory on macOS. Almost all troubleshooting reduces to:
- Which prefix/bottle is the app installed in?
- What Windows version is that prefix emulating? (Win7, Win10, Win11)
- What DLLs/runtimes are installed? (DirectX, .NET, VCRedist, DXVK)
- Is the failure at install, launch, or runtime?
Common prefix locations:
# CrossOver
~/Library/Application Support/CrossOver/Bottles/<BottleName>/
# Vanilla Wine
~/.wine/ # legacy default
~/Library/Application Support/Wine/ # newer Homebrew default
# Whisky
~/Library/Application Support/Whisky/Bottles/<uuid>/
# Kegworks/Wineskin wrapper
/Applications/YourApp.app/Contents/Resources/| Architecture | How Windows Apps Run | Performance Notes |
|---|---|---|
| Apple Silicon (arm64) | x86_64 → ARM translation via Wine + Rosetta 2 | DXVK/MoltenVK→Metal path preferred; expect ~15-30% overhead |
| Intel (x86_64) | Native x86_64 execution | Better compatibility; GPU driver limited on older Macs |
# Find ALL bottles/prefixes on this Mac
find ~/Library/Application\ Support -maxdepth 3 -iname "system.reg" 2>/dev/null
# Run with debug logging (vanilla Wine) — BEST for "why won't it launch"
WINEDEBUG=+loaddll,+seh,+module wine "/path/to/app.exe" > ~/Desktop/winelog.txt 2>&1
# Graphics/DirectX specific logging
WINEDEBUG=+d3d,+dxgi,+d3d11 wine "/path/to/app.exe" 2> ~/Desktop/gfx.log
# CrossOver CLI (use CrossOver's own wine binary + bottle env)
CX_BOTTLE="MyBottle" /Applications/CrossOver.app/Contents/SharedSupport/CrossOver/bin/wine "app.exe"
# Install common runtimes (run INSIDE the target prefix)
export WINEPREFIX=~/path/to/prefix
winetricks corefonts vcrun2019 dotnet48 d3dx9 dxvk
# Enable DXVK HUD for performance debugging
export DXVK_HUD=fps,frametimes,gpuload
wine "/path/to/app.exe"These CANNOT be fixed on ANY Wine-based layer:
| Blocker | Examples | Why |
|---|---|---|
| Kernel-level anti-cheat | Easy Anti-Cheat (kernel mode), BattlEye, Riot Vanguard | Requires real Windows kernel driver; Wine has no kernel mode |
| Certain DRM | Some Denuvo, SecuROM, StarForce | Kernel/low-level hooks Wine cannot replicate |
| DirectX 12 features | Ray tracing, mesh shaders, sampler feedback | DXVK/vkd3d-proton still catching up |
| Windows kernel drivers | Some hardware drivers, virtualization tools | No Windows kernel in Wine |
Tell users plainly: "This game has kernel-level anti-cheat (EAC/BattlEye/Vanguard) — it will NOT run on Wine/CrossOver/Whisky on macOS. No workaround exists."
- WineHQ AppDB — Community compatibility database
- CrossOver Compatibility Center — Official CodeWeavers database
- WineHQ Wiki — Official documentation
- DXVK GitHub — D3D9/10/11 → Vulkan
- VKD3D-Proton GitHub — D3D12 → Vulkan
- MoltenVK — Vulkan → Metal (macOS)
- Game Porting Toolkit — Apple's D3D→Metal
MIT License — Free to use, modify, and distribute.
Built for AI agents to help users run Windows software on macOS — regardless of which compatibility layer they choose.