xcode-preview-capture— agent skill

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

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

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

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