device-screenshot

name

device-screenshot

description

This skill should be used when capturing screenshots from connected devices during development. Use this when users request to capture device screens, take screenshots, analyze device UI, or inspect layout issues on iOS Simulator, physical iOS devices, or Android devices. Typical triggers include "capture screen", "take a screenshot of the device", "show me what's on the device", or "analyze the current screen".

Device Screenshot

Overview

Capture screenshots from iOS Simulators, physical iOS devices, or Android devices during development. Use this skill to inspect UI layouts, debug rendering issues, verify text/color display, or capture device state for analysis.

When to Use This Skill

Use this skill when users request to:

• Capture a screenshot from a connected device
• Analyze what's currently displayed on a device screen
• Debug layout rendering issues or UI problems
• Verify how elements are displayed (text, colors, spacing, etc.)
• Take snapshots during development for comparison or documentation

Common user requests that trigger this skill:

• "Capture screen for device"
• "Take a screenshot of the simulator"
• "Show me what's on the device right now"
• "Analyze the current screen"
• "Get a screenshot so we can see the layout issue"

Quick Start

iOS Simulator

To capture a screenshot from the currently running iOS Simulator:

xcrun simctl io booted screenshot $path

Example:

xcrun simctl io booted screenshot /tmp/simulator_screenshot.png

Requirements:

• iOS Simulator must be running (booted)
• Xcode Command Line Tools must be installed

Common issues:

• If "No devices are booted" error occurs, ensure the iOS Simulator is running
• The simulator must be the active/focused simulator if multiple are running

Android Device

To capture a screenshot from a connected Android device or emulator:

adb shell screencap -p > $path

Example:

adb shell screencap -p > /tmp/android_screenshot.png

Requirements:

• Android device or emulator must be connected
• ADB (Android Debug Bridge) must be installed and in PATH
• USB debugging must be enabled on physical devices

Common issues:

• If "device not found" error occurs, run adb devices to verify connection
• For multiple devices, specify device with adb -s <device_id> shell screencap -p > $path

Physical iOS Device

To capture a screenshot from a physical iPhone or iPad connected via USB, use the provided script:

scripts/ios_screenshot.sh $path

Example:

scripts/ios_screenshot.sh /tmp/iphone_screenshot.png

Requirements:

• Physical iOS device must be connected via USB
• Device must be trusted (paired with the Mac)
• Xcode must be installed
• The device should be unlocked

How it works:

1. Verifies an iOS device is connected using xcrun devicectl
2. Opens Xcode and triggers the screenshot interface (Shift+Cmd+2)
3. Automatically clicks the "Take Screenshot" button
4. Captures the most recent screenshot from Desktop
5. Copies it to the specified output path
6. Cleans up the Desktop screenshot file

Common issues:

• If "No connected iOS devices found" error occurs, check USB connection and trust status
• Ensure Xcode has proper permissions to control the system
• The device should be unlocked during screenshot capture

Workflow

Standard Screenshot Capture Process

1. Determine device type - Identify whether the user wants to capture from iOS Simulator, physical iOS device, or Android device

2. Verify device status - Ensure the device is connected and accessible:

   • iOS Simulator: Check if simulator is running
   • Android: Verify with adb devices
   • Physical iOS: Check connection with xcrun devicectl list devices

3. Choose output path - Determine where to save the screenshot:

   • Use /tmp/ for temporary analysis
   • Use project-specific paths for documentation
   • Default to /tmp/device_screenshot.png if not specified

4. Execute capture command - Run the appropriate command based on device type

5. Verify capture success - Check that the screenshot file was created and is valid

6. Analyze if requested - If the user requested analysis, read the screenshot and provide insights about:

   • Layout issues or rendering problems
   • Text display, colors, or spacing concerns
   • UI element positioning or alignment
   • Any visible bugs or inconsistencies

Example Interaction Flow

User request: "Take a screenshot of the simulator and tell me if the button is aligned correctly"

Process:

1. Determine device type → iOS Simulator
2. Choose output path → /tmp/sim_screenshot.png
3. Execute: xcrun simctl io booted screenshot /tmp/sim_screenshot.png
4. Verify file exists
5. Read the screenshot image
6. Analyze button alignment and provide feedback

Best Practices

• Always verify device connection before attempting screenshot capture
• Use descriptive output paths to make screenshots easy to identify later
• Clean up temporary screenshots after analysis to avoid clutter
• Default to /tmp/ directory for temporary analysis screenshots
• For physical iOS devices, ensure Xcode has accessibility permissions
• When analyzing, be specific about UI issues found (positioning, colors, text, etc.)

Troubleshooting

iOS Simulator Issues

• "No devices are booted" → Start the iOS Simulator from Xcode
• Permission denied → Ensure Xcode Command Line Tools are properly installed

Android Issues

• "device not found" → Run adb devices to verify device connection
• "adb: command not found" → Install Android SDK Platform Tools and add to PATH
• Multiple devices connected → Use adb -s <device_id> to specify target device

Physical iOS Issues

• "No connected iOS devices found" → Check USB connection and device trust status
• AppleScript errors → Grant Xcode accessibility permissions in System Preferences
• Screenshot not captured → Ensure device is unlocked and Xcode is properly installed
• Button not found → Update Xcode or check if the UI has changed in recent versions