| name | preview-build |
| description | Build and capture SwiftUI previews for visual analysis. Use when the user asks to preview a SwiftUI view, capture a simulator screenshot, or visually inspect iOS UI components. Supports Xcode projects, SPM packages, and standalone Swift files. |
Xcode Preview Capture Skill
Build SwiftUI views and capture screenshots of their rendered output for visual analysis.
Installation Path
Scripts are located at ${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}/scripts/
Compatibility: If ~/XcodePreviews doesn't exist, fall back to ~/Claude-XcodePreviews (legacy name). The PREVIEW_BUILD_PATH environment variable overrides both.
Available Commands
Unified Preview (Recommended)
Auto-detects project type and uses the best approach:
"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview \
<path-to-file.swift> \
--output /tmp/preview.png
Quick Capture (Current Simulator)
"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/capture-simulator.sh \
--output /tmp/preview-capture.png
Xcode Project with #Preview
Fast builds by injecting a minimal PreviewHost target (handled automatically by the unified script):
"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview \
<path-to-file.swift> \
--project <path.xcodeproj> \
--output /tmp/preview.png
SPM Package Preview
Auto-detected from Package.swift in parent directories:
"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview \
<path-to-file.swift> \
--output /tmp/preview.png
Standalone Swift File
Build a standalone Swift file with system frameworks only:
"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview \
<path-to-file.swift> \
--output /tmp/preview.png
Workflow
When the user asks to preview a SwiftUI view:
-
Identify the target: Determine what needs to be previewed (Swift file, project scheme, or current simulator state)
-
Build and capture: Run the appropriate script
-
Read and analyze: Use the Read tool to view the captured PNG at /tmp/preview.png
-
Report findings:
- Layout: Structure and arrangement
- Visual elements: Buttons, text, images
- Styling: Colors, fonts, spacing
- Issues: Alignment, overflow, accessibility
- Suggestions: Improvements
Parameters
| Option | Description |
|---|
--project <path> | Xcode project file |
--workspace <path> | Xcode workspace file |
--package <path> | SPM Package.swift path |
--module <name> | Target module (auto-detected) |
--simulator <name> | Simulator name (default: iPhone 17 Pro) |
--output <path> | Output screenshot path |
--verbose | Show detailed build output |
Error Handling
- No simulator booted: Run
sim-manager.sh boot "iPhone 17 Pro"
- Build failure: Show error, suggest fixes, offer to retry
- Resource bundle crash: The dynamic script auto-includes Tuist and common bundle patterns
- Missing imports: Check if the target module needs to be added to imports
