preview-build

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:

1. Identify the target: Determine what needs to be previewed (Swift file, project scheme, or current simulator state)

2. Build and capture: Run the appropriate script

3. Read and analyze: Use the Read tool to view the captured PNG at /tmp/preview.png

4. 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