Add flutter-app-runtime Agent Skill for runtime interaction and proactive hot reload

README.md

@@ -19,6 +19,7 @@ Refer to [Get started developing with AI](https://docs.flutter.dev/ai/get-starte
 | [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. | Change the background color to red |
 | [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 |

resources/flutter_skills.yaml

@@ -431,4 +431,44 @@
     - 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
+    - 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.
+  examplePrompt: "Change the background color to red"
+
+  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 the `dtd` tool (via `listDtdUris` / `listConnectedApps`) 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

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. Use the `dtd` tool (with `listDtdUris` and `connect`, or `listConnectedApps`) 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 <device-id> --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 background color to red"
+
+**Execution Steps:**
+1. Locate the target background widget (e.g., `Scaffold`, `Container`) in the Dart code.
+2. Update `backgroundColor: Colors.red` or `color: Colors.red`.
+3. Save the file.
+4. Immediately execute `hot_reload` using the active `appUri`.
+5. Confirm successful reload via tool output.