From 79a02f1dd0e88a123992d219290521d4c5510aac Mon Sep 17 00:00:00 2001 From: Jaime Wren Date: Fri, 7 Aug 2026 14:48:42 -0700 Subject: [PATCH] Add flutter-app-runtime skill for runtime interaction and proactive hot reload - Add the `flutter-app-runtime` skill definition to `resources/flutter_skills.yaml`. - Generate `skills/flutter-app-runtime/SKILL.md` to guide agents in discovering running applications via DTD/MCP, proactively hot reloading on widget changes, and diagnosing runtime errors. - Update `README.md` with the new skill entry. --- README.md | 1 + resources/flutter_skills.yaml | 41 ++++++++++- skills/flutter-app-runtime/SKILL.md | 103 ++++++++++++++++++++++++++++ 3 files changed, 144 insertions(+), 1 deletion(-) create mode 100644 skills/flutter-app-runtime/SKILL.md diff --git a/README.md b/README.md index 06a30a06..a0c959b9 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,7 @@ npx skills@1.5.17 update | [flutter-add-integration-test](skills/flutter-add-integration-test/SKILL.md) | Configures Flutter Driver for app interaction and converts MCP actions into permanent integration tests. Use when adding integration testing to a project, exploring UI components via MCP, or automating user flows with the integration_test package. | Add an integration test that validates the checkout experience | | [flutter-add-widget-preview](skills/flutter-add-widget-preview/SKILL.md) | Adds interactive widget previews to the project using the previews.dart system. Use when creating new UI components or updating existing screens to ensure consistent design and interactive testing. | Create a preview for the ProductCard widget with different price states | | [flutter-add-widget-test](skills/flutter-add-widget-test/SKILL.md) | Implement a component-level test using `WidgetTester` to verify UI rendering and user interactions (tapping, scrolling, entering text). Use when validating that a specific widget displays correct data and responds to events as expected. | Add a widget test for the CustomButton to verify the onTap callback is called | +| [flutter-app-runtime](skills/flutter-app-runtime/SKILL.md) | 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. | | | [flutter-apply-architecture-best-practices](skills/flutter-apply-architecture-best-practices/SKILL.md) | Architects a Flutter application using the recommended layered approach (UI, Logic, Data). Use when structuring a new project or refactoring for scalability. | Refactor the authentication flow to follow the recommended layered architecture | | [flutter-build-responsive-layout](skills/flutter-build-responsive-layout/SKILL.md) | Use `LayoutBuilder`, `MediaQuery`, or `Expanded/Flexible` to create a layout that adapts to different screen sizes. Use when you need the UI to look good on both mobile and tablet/desktop form factors. | Make the home screen responsive so it displays a grid on tablets and a list on phones | | [flutter-fix-layout-issues](skills/flutter-fix-layout-issues/SKILL.md) | Fixes Flutter layout errors (overflows, unbounded constraints) using Dart and Flutter MCP tools. Use when addressing "RenderFlex overflowed", "Vertical viewport was given unbounded height", or similar layout issues. | Fix the overflow error on the profile page when the keyboard is visible | diff --git a/resources/flutter_skills.yaml b/resources/flutter_skills.yaml index f055e473..f6cadce6 100644 --- a/resources/flutter_skills.yaml +++ b/resources/flutter_skills.yaml @@ -431,4 +431,43 @@ - https://docs.flutter.dev/cookbook/networking/send-data - https://docs.flutter.dev/cookbook/networking/update-data - https://docs.flutter.dev/data-and-backend/serialization - - https://docs.flutter.dev/data-and-backend/serialization/json \ No newline at end of file + - https://docs.flutter.dev/data-and-backend/serialization/json +- 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. + + instructions: | + This Skill enables zero-configuration interaction with running Dart and Flutter + applications. The Dart MCP server manages the underlying connection to the + application's VM service, allowing the agent to focus on high-level runtime + operations. + + Pre-requisite: + The Dart and Flutter MCP server must be configured and active. + + Core capabilities include: + - Hot Reload: Proactively trigger hot reloads to immediately 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. + + Decision workflow: + 1. Identify Targets: Use `list_running_apps` or the `dtd` tool to discover and connect + to running application instances in the current workspace. If no app is running, + inform the user but do not let it stop you from completing code edits. + 2. Verify Connection: Use `dtd` or `vm_service` to ensure the required `appUri` + is active and matches the project's workspace. Re-sync via `dtd` if necessary. + 3. Proactive Hot Reload & Ops: Whenever edits or changes are made to Flutter UI widgets + or Dart code, proactively trigger `hot_reload` across all targeted instances immediately + to maintain visual consistency. For diagnosis, query live logs with `get_runtime_errors` + first or inspect UI with `widget_inspector`. Use `hot_restart` to reset state across + all devices when debugging foundational logic. + + Sample scenarios include proactive hot reloading after widget modifications, + autonomous bug fixing by fetching exceptions, inspecting and modifying UI using + the widget inspector, and multi-device synchronization for global changes like themes. + resources: + - https://docs.flutter.dev/ai/mcp-server \ No newline at end of file diff --git a/skills/flutter-app-runtime/SKILL.md b/skills/flutter-app-runtime/SKILL.md new file mode 100644 index 00000000..901520f8 --- /dev/null +++ b/skills/flutter-app-runtime/SKILL.md @@ -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}"`. +- [ ] 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 --dart-define=ENABLE_FLUTTER_DRIVER=true`. +- [ ] 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.