name: simulator-screenshot
description: Capture screenshots from iOS Simulator or Android Emulator using the bundled simulator-screenshot.sh script. Use when asked to take simulator/emulator screenshots, list available devices, select a specific simulator or emulator by ID/name, or return JSON output for automation.
license: MIT
metadata:
author: Krzysztof Moch

Simulator Screenshot

Overview

Use this skill to capture screenshots from iOS Simulator or Android Emulator via a single script with consistent JSON output. It supports listing devices, selecting by name or ID, and saving screenshots to a chosen path.
Useful for verifying UI changes, debugging layouts, or documenting app states during development.

If user is working on iOS/Android App use this tool to verify visual aspects by capturing simulator/emulator screenshots on demand.

Quick Start

Use scripts/simulator-screenshot.sh from this skill folder.

# List iOS simulators (JSON)
scripts/simulator-screenshot.sh ios --list --json

# Capture from the booted iOS simulator
scripts/simulator-screenshot.sh ios ./screenshot.png --json

# Capture from a specific iOS simulator by name
scripts/simulator-screenshot.sh ios ./screenshot.png --id "iPhone 15 Pro" --json

# List Android emulators/devices (JSON)
scripts/simulator-screenshot.sh android --list --json

# Capture from a specific Android emulator by serial
scripts/simulator-screenshot.sh android ./screenshot.png --id emulator-5554 --json

Workflow

Pre steps:
1. If user have not specified location to save screenshot, create agent_screenshots folder in the current directory.
2. Generate names for screenshots basing on context of usage eg. login_screen-ios.png, settings_page-ios.png.
3. Use --max-size 1024 unless the user specifies another size.

Main steps:
1. Choose platform: ios or android.
2. If device is unknown, run --list --json and pick a device:
- iOS: use device name or UDID.
- Android: use running device serial (e.g., emulator-5554).
3. Capture with optional --id and an output path, including --max-size 1024 unless specified otherwise.
4. Parse JSON output and check status for success or error.

Output Notes

• Always pass --json for machine-readable output.
• Success JSON includes path, platform, device_id (if provided), and timestamp.
• Error JSON includes message, platform, and timestamp.

Requirements

• iOS: macOS with Xcode Command Line Tools and jq.
• Android: Android SDK adb in PATH and jq. Optional emulator for listing AVDs.