Flutter Skill

Give your AI Agent eyes and hands inside your Flutter app. This skill enables comprehensive control of Flutter applications for testing, debugging, and automation.

Installation

Option 1: npx (Recommended)

{
  "flutter-skill": {
    "command": "npx",
    "args": ["flutter-skill"]
  }
}

Option 2: Global Install

dart pub global activate flutter_skill

Then configure:

{
  "flutter-skill": {
    "command": "flutter_skill",
    "args": ["server"]
  }
}

Available Tools

Connection

• •connect_app - Connect to a running Flutter app via WebSocket URI
• •launch_app - Launch a Flutter app with auto-setup (adds dependencies, patches main.dart)

UI Inspection

• •inspect - Get interactive elements (buttons, text fields, etc.)
• •get_widget_tree - Full widget tree structure with configurable depth
• •get_widget_properties - Widget details (size, position, visibility)
• •get_text_content - Extract all visible text from screen
• •find_by_type - Find all widgets of a specific type

Interactions

• •tap - Tap element by key or text
• •double_tap - Double tap gesture
• •long_press - Long press gesture
• •swipe - Swipe up/down/left/right
• •drag - Drag from one element to another
• •scroll_to - Scroll element into view
• •enter_text - Input text into text field

State Validation

• •get_text_value - Get text field value
• •get_checkbox_state - Get checkbox checked state
• •get_slider_value - Get slider current value
• •wait_for_element - Wait for element to appear (with timeout)
• •wait_for_gone - Wait for element to disappear

Screenshots

• •screenshot - Capture full app screenshot (base64 PNG)
• •screenshot_element - Capture specific element screenshot

Navigation

• •get_current_route - Get current route name
• •go_back - Navigate back
• •get_navigation_stack - Get navigation history

Debug & Logs

• •get_logs - Application logs
• •get_errors - Error messages
• •get_performance - Performance metrics
• •clear_logs - Clear log buffer
• •hot_reload - Trigger hot reload

Usage Examples

Test a Counter App

1. Launch the app: launch_app with project_path="/path/to/app"
2. Inspect UI: inspect
3. Tap increment: tap with key="increment_button"
4. Verify: get_text_content to see updated counter

Test a Login Flow

1. Enter email: enter_text with key="email_field", text="user@example.com"
2. Enter password: enter_text with key="password_field", text="password123"
3. Tap login: tap with key="login_button"
4. Wait for home: wait_for_element with key="home_screen", timeout=5000

Debug an Issue

1. Connect: connect_app with uri="ws://127.0.0.1:xxxxx/ws"
2. Check errors: get_errors
3. View logs: get_logs
4. Take screenshot: screenshot

Best Practices

Use Widget Keys

For reliable element identification, target apps should use ValueKey:

ElevatedButton(
  key: const ValueKey('submit_button'),
  onPressed: _submit,
  child: const Text('Submit'),
)

Element Finding Priority

1. •Key (most reliable): tap with key="submit_button"
2. •Text content: tap with text="Submit"
3. •Widget type: find_by_type with type="ElevatedButton"

Links

• •GitHub Repository
• •pub.dev Package
• •npm Package