xcode-preview-capture

name	xcode-preview-capture
description	Build and capture Xcode/SwiftUI previews for visual analysis. Use when you need to see rendered UI output, verify layouts, or inspect visual components.

Overview

This skill allows you to build SwiftUI views and capture screenshots of their rendered output for visual analysis. It supports:

• Building standalone Swift files containing SwiftUI views
• Building views from existing Xcode projects
• Building views from SPM packages
• Capturing the current simulator screen
• Analyzing the captured screenshots

Installation Path

Scripts are located at ${CLAUDE_PLUGIN_ROOT}/scripts/

Available Commands

Unified Preview (Recommended)

Auto-detects project type and uses the best approach:

"${CLAUDE_PLUGIN_ROOT}"/scripts/preview \
  <path-to-file.swift> \
  --output /tmp/preview.png

Quick Capture (Current Simulator)

Capture a screenshot of whatever is currently displayed on the booted simulator.

"${CLAUDE_PLUGIN_ROOT}"/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):

"${CLAUDE_PLUGIN_ROOT}"/scripts/preview \
  <path-to-file.swift> \
  --project <path.xcodeproj> \
  --output /tmp/preview.png

SPM Package Preview

Auto-detected from Package.swift in parent directories:

"${CLAUDE_PLUGIN_ROOT}"/scripts/preview \
  <path-to-file.swift> \
  --output /tmp/preview.png

Standalone Swift File

Build a standalone Swift file with system frameworks only:

"${CLAUDE_PLUGIN_ROOT}"/scripts/preview \
  <path-to-file.swift> \
  --output /tmp/preview.png

Workflow

When the user invokes /preview, follow this workflow:

1. Identify the target: Determine what needs to be previewed:

   • A specific Swift file
   • An Xcode project/workspace with a scheme
   • The current simulator state

2. Build and capture: Use the appropriate script based on the target

3. Read and analyze: Use the Read tool to view the captured PNG image

4. Report findings: Describe what you see in the preview, including:

   • Layout and structure
   • Colors and styling
   • Any potential issues (alignment, overflow, etc.)
   • Suggestions for improvement

Parameters

The user can specify:

• file: Path to a Swift file to preview
• project: Path to an Xcode project
• workspace: Path to an Xcode workspace
• scheme: Build scheme name
• simulator: Simulator to use (default: "iPhone 17 Pro")
• wait: Seconds to wait before capture (default: 3)

Example Usage

User: /preview ContentView.swift
User: /preview --project MyApp.xcodeproj --scheme MyApp
User: /preview --capture-only

Error Handling

If the build fails:

1. Show the build error output
2. Suggest fixes based on the error messages
3. Offer to try again after fixes are applied

If no simulator is booted:

1. List available simulators
2. Offer to boot one

Output

After capturing, always:

1. Confirm the screenshot was saved
2. Read the image using the Read tool
3. Provide analysis of what's visible