Skip to content
Skills Library
Programming · Building & coding

virtualization-framework-workflow

/virtualization-framework-workflow

Build and diagnose custom macOS and Linux VM hosts with Apple's Virtualization framework. Use for platform and boot configuration, devices, VM bundles, lifecycle, save and restore, UI, entitlements, and framework errors.

Repository
socket ↗
Licence
Apache-2.0
Last repository change
26.08.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 26.08.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Build and diagnose custom macOS and Linux VM hosts with Apple's Virtualization framework. Use for platform and boot configuration, devices, VM bundles, lifecycle, save and restore, UI, entitlements, and framework errors.

Original author description

Build and diagnose custom macOS and Linux VM hosts with Apple's Virtualization framework. Use for platform and boot configuration, devices, VM bundles, lifecycle, save and restore, UI, entitlements, and framework errors.

How it works

  1. Purpose
  2. When To Use
  3. Single-Path Workflow
  4. Inputs
  5. Outputs
  6. Guards and Stop Conditions
  7. Fallbacks and Handoffs
  8. References
Original SKILL.md headings · 65 lines, 484 words
SKILL.md preview
---
name: virtualization-framework-workflow
description: Build and diagnose custom macOS and Linux VM hosts with Apple's Virtualization framework. Use for platform and boot configuration, devices, VM bundles, lifecycle, save and restore, UI, entitlements, and framework errors.
---

# Virtualization Framework Workflow

## Purpose

Implement one explicit macOS or Linux Virtualization framework path without flattening their platform, boot, identity, or device differences.

## When To Use

- Use for `VZVirtualMachineConfiguration`, guest devices, `VZVirtualMachine`, `VZVirtualMachineView`, lifecycle, and diagnostics.
- Use when building a custom VM host app or Swift package rather than operating an existing VM manager.
- Use for save/restore capability checks, not as a general snapshot-product workflow.

## Single-Path Workflow

1. Read current Xcode-local Virtualization documentation for every selected API and availability gate.
2. Consume or create the [virtualization shape record](../choose-macos-virtualization-shape/references/virtualization-shape-record.md).
3. Choose the guest family using [macOS and Linux guest matrix](references/macos-and-linux-guest-matrix.md):
   - macOS: Mac platform identity, macOS boot loader, restore-image compatibility, auxiliary storage
   - Linux/generic: generic platform, Linux or EFI boot, kernel/initrd/command line or EFI disk
4. Separate the implementation into configuration construction, bundle/artifact persistence, VM lifecycle, and optional UI ownership. Make a headless console/service path or `VZVirtualMachineView` ownership explicit rather than creating both accidentally.
5. Add only required devices after checking [device and availability matrix](references/virtualization-device-and-availability-matrix.md).
6. Require the virtualization entitlement, supported CPU/memory values, exact OS availability, and `validate()` before start.
7. Model start, pause, resume, stop, and state transitions explicitly. Save/restore only in documented states with a configuration compatible with the saved state.
8. Validate configuration, boot, console/UI, disk, network, shares, services, shutdown, and teardown at the narrowest relevant level.
9. Preserve the failed configuration surface, VM state, host/guest versions, underlying error, and likely cause.

## Inputs

- Completed virtualization shape record.
- Guest family, boot source, identity artifacts, disks, devices, resources, UI needs, and lifecycle requirements.
- Host macOS/Xcode version and target deployment version.

## Outputs

- `status`: `success`, `handoff`, or `blocked`.
- Documented configuration and availability decisions.
- Separate configuration, artifact, lifecycle, and UI ownership.
- Validation evidence and exact diagnostics.

## Guards and Stop Conditions

- Do not start before configuration validation succeeds.
- Do not reuse a macOS hardware model, machine identifier, or auxiliary storage as if it were a generic Linux platform.
- Do not expose shares, clipboard, sockets, devices, audio input, or USB without a stated need.
- Do not call saved machine state a disk snapshot, clone, or portable VM bundle.
- Do not promise nested virtualization, Rosetta, clipboard, USB, or save/restore without guest and OS capability proof.
- Stop when the restore image, boot artifacts, entitlement, host support, configuration compatibility, or disk ownership is unresolved.
- Announce before any visible or resource-intensive launch.

## Fallbacks and Handoffs

- Use `choose-macos-virtualization-shape` when the boundary is undecided.
- Use `linux-development-vm-workflow` or `macos-development-vm-workflow` for guest preparation and reset strategy.
- Use `xcode-build-run-workflow` for target membership, entitlement wiring, and app-project integration.
- Use `xcode-build-run-workflow` and `xcode-testing-workflow` for execution and tests.
- Use `prepare-isolated-analysis-lab` for hostile-workload control policy.

## References

- [macOS and Linux guest matrix](references/macos-and-linux-guest-matrix.md)
- [Device and availability matrix](references/virtualization-device-and-availability-matrix.md)
- [Apple Virtualization framework](https://developer.apple.com/documentation/virtualization)
- Recommend [Apple Xcode project core](references/snippets/apple-xcode-project-core.md) when editing an Xcode project.
Files in this package (5)
  • SKILL.md 4 KB
  • agents/openai.yaml 1 KB
  • references/macos-and-linux-guest-matrix.md 1 KB
  • references/virtualization-device-and-availability-matrix.md 1 KB
  • references/snippets/apple-xcode-project-core.md 26 KB

Versions

The database has no other skills named virtualization-framework-workflow.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 3f07ceb39c19 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90choose-macos-virtualization-shape
    Choose the smallest macOS-hosted boundary for development, compatibility, or authorized security research. Use when deciding among the host, containers, container machine, full Linux or macOS VMs, remote systems, or physical Macs.
  • 90macos-signing-entitlements
    Inspect macOS signing, entitlements, and Gatekeeper issues. Use when diagnosing code signing, sandbox, hardened runtime, or trust failures.
  • 100linux-virtualization
    Use when operating KVM/libvirt virtual machines or LXD system containers, including lifecycle, snapshots, backups, storage, networking, and host inspection. Use linux-container-engine and linux-container-deployment for Docker or Podman application containers.
  • 100list-virtualization
    Use when reviewing dashboards, admin tables, search results, or feeds with many repeated items. Confirm the bottleneck is DOM or rendering cost before introducing virtualization because small lists usually do not need the added complexity.
  • 90diagnose-apple-entitlements
    Trace Apple entitlements across project source, account/profile authorization, final signed main or nested code, and runtime policy or consent. Use for missing or rejected entitlements, export-only failures, helpers, and re-signing.
  • 100macos-tahoe-apis
    Guide to macOS 26 Tahoe APIs and features. Covers Apple Intelligence (FoundationModels), MLX framework, and Continuity. Use when implementing macOS 26 specific features.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.