Add flutter-app-runtime skill for runtime interaction and proactive hot reload #219
+144
−1
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| --- | ||
| name: flutter-app-runtime | ||
| description: Interacts with running Dart and Flutter applications via the Dart MCP server to enable hot reload, hot restart, widget inspection, and error fetching. Use when modifying UI widgets, debugging errors, inspecting running apps, or proactively hot reloading whenever changes are made to Flutter UI widgets. | ||
| metadata: | ||
| model: models/gemini-3.1-pro-preview | ||
| last_modified: Fri, 07 Aug 2026 21:16:50 GMT | ||
| --- | ||
| # Managing Dart and Flutter Applications via MCP | ||
|
|
||
| ## Contents | ||
| - [Core Capabilities](#core-capabilities) | ||
| - [Workflow: Application Discovery and Connection](#workflow-application-discovery-and-connection) | ||
| - [Workflow: UI Modification and Hot Reloading](#workflow-ui-modification-and-hot-reloading) | ||
| - [Workflow: Runtime Debugging and Error Resolution](#workflow-runtime-debugging-and-error-resolution) | ||
| - [Workflow: UI Interaction via Flutter Driver](#workflow-ui-interaction-via-flutter-driver) | ||
| - [Examples](#examples) | ||
|
|
||
| ## Core Capabilities | ||
|
|
||
| The Dart and Flutter MCP server manages the underlying connection to the application's VM service via the Dart Tooling Daemon (`dtd`). Assume the server is already configured and active. | ||
|
|
||
| - **Hot Reload:** Proactively push visual feedback for UI widget updates and simple logic changes. | ||
| - **Hot Restart:** Reset the app state for deep non-widget changes or clean resets. | ||
| - **Widget Inspection:** Query tree structures and identify UI hierarchy names. | ||
| - **Error Fetching:** Retrieve live runtime exceptions and trace pointers live. | ||
| - **Package Management:** Search pub.dev and manage `pubspec.yaml` dependencies. | ||
|
|
||
| ## Workflow: Application Discovery and Connection | ||
|
|
||
| Execute this workflow before attempting runtime operations. | ||
|
|
||
| - [ ] 1. Run `list_running_apps` or use the `dtd` tool to discover active application instances in the current workspace. | ||
| - [ ] 2. Extract the `appUri` for the target application. | ||
| - [ ] 3. Verify the connection using `dtd` or `vm_service` to ensure the `appUri` matches the project's workspace. Re-sync via `dtd` if necessary. | ||
| - [ ] 4. **Conditional:** If no app is running, inform the user immediately, but **do not stop**. Proceed with static code edits and file modifications. | ||
|
|
||
| ## Workflow: UI Modification and Hot Reloading | ||
|
|
||
| Whenever modifying Flutter UI widgets or Dart code, follow this feedback loop to maintain visual consistency. | ||
|
|
||
| - [ ] 1. Implement the requested code changes in the target `.dart` files. | ||
| - [ ] 2. **Conditional:** | ||
| - If editing Flutter UI widgets or simple methods, trigger `hot_reload` across all targeted instances immediately. | ||
| - If modifying foundational logic, state initialization, or `main()`, trigger `hot_restart` to reset state across all devices. | ||
| - [ ] 3. Run `get_runtime_errors` to verify the reload/restart did not introduce new exceptions. | ||
| - [ ] 4. If errors exist, review the stack trace, apply a fix, and repeat step 2. | ||
|
|
||
| ## Workflow: Runtime Debugging and Error Resolution | ||
|
|
||
| When tasked with fixing layout issues (e.g., RenderFlex overflow) or runtime exceptions, use this diagnostic loop. | ||
|
|
||
| - [ ] 1. Execute `get_runtime_errors` to fetch live exceptions from the running application. | ||
| - [ ] 2. Identify the failing widget or logic block from the stack trace. | ||
| - [ ] 3. Execute `widget_inspector` to query the live UI tree structure and understand the layout constraints causing the issue. | ||
| - [ ] 4. Apply the code fix to the relevant Dart file. | ||
| - [ ] 5. Trigger `hot_reload`. | ||
| - [ ] 6. Execute `get_runtime_errors` again to confirm the error is resolved. | ||
|
|
||
| ## Workflow: UI Interaction via Flutter Driver | ||
|
|
||
| To drive a running Flutter app (take screenshots, tap buttons, enter text), the app must be instrumented with `flutter_driver`. | ||
|
|
||
| - [ ] 1. Verify `flutter_driver` is in `pubspec.yaml`. If not, run `flutter pub add "flutter_driver:{sdk: flutter}"`. | ||
|
Contributor
There was a problem hiding this comment.
Suggested change: - [ ] 1. Verify `flutter_driver` is in `pubspec.yaml`. If not, run `flutter pub add 'dev:flutter_driver:{"sdk":"flutter"}'.` |
||
| - [ ] 2. Ensure the app's `main()` function conditionally enables the driver extension: | ||
| ```dart | ||
| import 'package:flutter_driver/driver_extension.dart'; | ||
|
|
||
| void main() { | ||
| if (const bool.fromEnvironment('ENABLE_FLUTTER_DRIVER')) { | ||
| enableFlutterDriverExtension(); | ||
| } | ||
| runApp(const MyApp()); | ||
| } | ||
| ``` | ||
| - [ ] 3. Instruct the user to launch the app with: `flutter run -d <device-id> --dart-define=ENABLE_FLUTTER_DRIVER=true`. | ||
|
Comment on lines
+64
to
+75
Contributor
There was a problem hiding this comment. Importing Suggested change: - [ ] 2. Ensure a separate entry point (e.g., `lib/main_test.dart`) is created to enable the driver extension without affecting production builds:
```dart
import 'package:flutter_driver/driver_extension.dart';
import 'main.dart' as app;
void main() {
enableFlutterDriverExtension();
app.main();
}
|
||
| - [ ] 4. Use the `dtd` tool to discover the app and `flutter_driver_command` to drive its UI. | ||
| - [ ] 5. **Conditional (Web Targets):** If the target is a web build, do not use `flutter_driver` finder-based commands (screenshots/taps). Instead, rely on a browser-driving MCP. Ensure the user runs `flutter run -d web-server` so DTD connects properly to the driven browser. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Scenario: Adding a Package and Scaffolding UI | ||
|
|
||
| **Input:** "Add a line chart to map user scores over time." | ||
|
|
||
| **Execution Steps:** | ||
| 1. Execute `pub_dev_search` with query "line chart". | ||
| 2. Identify `fl_chart` as the optimal package. | ||
| 3. Add dependency to `pubspec.yaml`. | ||
| 4. Generate the widget code using `fl_chart` boilerplate. | ||
| 5. Insert the widget into the target UI file. | ||
| 6. Trigger `hot_reload`. | ||
| 7. Run `get_runtime_errors` to ensure no missing constraints or syntax errors exist. | ||
|
|
||
| ### Scenario: Proactive Hot Reloading | ||
|
|
||
| **Input:** "Change the primary button color to blue and increase the padding to 16." | ||
|
|
||
| **Execution Steps:** | ||
| 1. Locate the target `ElevatedButton` or `Container` in the Dart code. | ||
| 2. Update `style: ElevatedButton.styleFrom(backgroundColor: Colors.blue)` and `padding: EdgeInsets.all(16)`. | ||
| 3. Save the file. | ||
| 4. Immediately execute `hot_reload` using the active `appUri`. | ||
| 5. Confirm successful reload via tool output. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The example prompt column for the
flutter-app-runtimeskill is currently empty. To maintain consistency with other skills in the table, please provide a representative example prompt.