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