Skip to content

Commit bb2d719

Browse files
jwrenjwren
committed
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.
1 parent 66b6d25 commit bb2d719

3 files changed

Lines changed: 144 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ npx skills@1.5.17 update
7979
| [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 |
8080
| [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 |
8181
| [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 |
82+
| [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. | |
8283
| [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 |
8384
| [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 |
8485
| [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‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -431,4 +431,43 @@
431431
- https://docs.flutter.dev/cookbook/networking/send-data
432432
- https://docs.flutter.dev/cookbook/networking/update-data
433433
- https://docs.flutter.dev/data-and-backend/serialization
434-
- https://docs.flutter.dev/data-and-backend/serialization/json
434+
- https://docs.flutter.dev/data-and-backend/serialization/json
435+
- name: flutter-app-runtime
436+
description: Interacts with running Dart and Flutter applications via the
437+
Dart MCP server to enable hot reload, hot restart, widget inspection, and
438+
error fetching. Use when modifying UI widgets, debugging errors, inspecting
439+
running apps, or proactively hot reloading whenever changes are made to
440+
Flutter UI widgets.
441+
442+
instructions: |
443+
This Skill enables zero-configuration interaction with running Dart and Flutter
444+
applications. The Dart MCP server manages the underlying connection to the
445+
application's VM service, allowing the agent to focus on high-level runtime
446+
operations.
447+
448+
Pre-requisite:
449+
The Dart and Flutter MCP server must be configured and active.
450+
451+
Core capabilities include:
452+
- Hot Reload: Proactively trigger hot reloads to immediately push visual feedback for UI widget updates and simple logic changes.
453+
- Hot Restart: Reset the app state for deep non-widget changes or clean resets.
454+
- Widget Inspection: Query tree structures and identify UI hierarchy names.
455+
- Error Fetching: Retrieve live runtime exceptions and trace pointers live.
456+
457+
Decision workflow:
458+
1. Identify Targets: Use the `dtd` tool (via `listDtdUris` / `listConnectedApps`) to discover and connect
459+
to running application instances in the current workspace. If no app is running,
460+
inform the user but do not let it stop you from completing code edits.
461+
2. Verify Connection: Use `dtd` or `vm_service` to ensure the required `appUri`
462+
is active and matches the project's workspace. Re-sync via `dtd` if necessary.
463+
3. Proactive Hot Reload & Ops: Whenever edits or changes are made to Flutter UI widgets
464+
or Dart code, proactively trigger `hot_reload` across all targeted instances immediately
465+
to maintain visual consistency. For diagnosis, query live logs with `get_runtime_errors`
466+
first or inspect UI with `widget_inspector`. Use `hot_restart` to reset state across
467+
all devices when debugging foundational logic.
468+
469+
Sample scenarios include proactive hot reloading after widget modifications,
470+
autonomous bug fixing by fetching exceptions, inspecting and modifying UI using
471+
the widget inspector, and multi-device synchronization for global changes like themes.
472+
resources:
473+
- https://docs.flutter.dev/ai/mcp-server

‎skills/flutter-app-runtime/SKILL.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
name: flutter-app-runtime
3+
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.
4+
metadata:
5+
model: models/gemini-3.1-pro-preview
6+
last_modified: Fri, 07 Aug 2026 21:16:50 GMT
7+
---
8+
# Managing Dart and Flutter Applications via MCP
9+
10+
## Contents
11+
- [Core Capabilities](#core-capabilities)
12+
- [Workflow: Application Discovery and Connection](#workflow-application-discovery-and-connection)
13+
- [Workflow: UI Modification and Hot Reloading](#workflow-ui-modification-and-hot-reloading)
14+
- [Workflow: Runtime Debugging and Error Resolution](#workflow-runtime-debugging-and-error-resolution)
15+
- [Workflow: UI Interaction via Flutter Driver](#workflow-ui-interaction-via-flutter-driver)
16+
- [Examples](#examples)
17+
18+
## Core Capabilities
19+
20+
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.
21+
22+
- **Hot Reload:** Proactively push visual feedback for UI widget updates and simple logic changes.
23+
- **Hot Restart:** Reset the app state for deep non-widget changes or clean resets.
24+
- **Widget Inspection:** Query tree structures and identify UI hierarchy names.
25+
- **Error Fetching:** Retrieve live runtime exceptions and trace pointers live.
26+
- **Package Management:** Search pub.dev and manage `pubspec.yaml` dependencies.
27+
28+
## Workflow: Application Discovery and Connection
29+
30+
Execute this workflow before attempting runtime operations.
31+
32+
- [ ] 1. Use the `dtd` tool (with `listDtdUris` and `connect`, or `listConnectedApps`) to discover active application instances in the current workspace.
33+
- [ ] 2. Extract the `appUri` for the target application.
34+
- [ ] 3. Verify the connection using `dtd` or `vm_service` to ensure the `appUri` matches the project's workspace. Re-sync via `dtd` if necessary.
35+
- [ ] 4. **Conditional:** If no app is running, inform the user immediately, but **do not stop**. Proceed with static code edits and file modifications.
36+
37+
## Workflow: UI Modification and Hot Reloading
38+
39+
Whenever modifying Flutter UI widgets or Dart code, follow this feedback loop to maintain visual consistency.
40+
41+
- [ ] 1. Implement the requested code changes in the target `.dart` files.
42+
- [ ] 2. **Conditional:**
43+
- If editing Flutter UI widgets or simple methods, trigger `hot_reload` across all targeted instances immediately.
44+
- If modifying foundational logic, state initialization, or `main()`, trigger `hot_restart` to reset state across all devices.
45+
- [ ] 3. Run `get_runtime_errors` to verify the reload/restart did not introduce new exceptions.
46+
- [ ] 4. If errors exist, review the stack trace, apply a fix, and repeat step 2.
47+
48+
## Workflow: Runtime Debugging and Error Resolution
49+
50+
When tasked with fixing layout issues (e.g., RenderFlex overflow) or runtime exceptions, use this diagnostic loop.
51+
52+
- [ ] 1. Execute `get_runtime_errors` to fetch live exceptions from the running application.
53+
- [ ] 2. Identify the failing widget or logic block from the stack trace.
54+
- [ ] 3. Execute `widget_inspector` to query the live UI tree structure and understand the layout constraints causing the issue.
55+
- [ ] 4. Apply the code fix to the relevant Dart file.
56+
- [ ] 5. Trigger `hot_reload`.
57+
- [ ] 6. Execute `get_runtime_errors` again to confirm the error is resolved.
58+
59+
## Workflow: UI Interaction via Flutter Driver
60+
61+
To drive a running Flutter app (take screenshots, tap buttons, enter text), the app must be instrumented with `flutter_driver`.
62+
63+
- [ ] 1. Verify `flutter_driver` is in `pubspec.yaml`. If not, run `flutter pub add "flutter_driver:{sdk: flutter}"`.
64+
- [ ] 2. Ensure the app's `main()` function conditionally enables the driver extension:
65+
```dart
66+
import 'package:flutter_driver/driver_extension.dart';
67+
68+
void main() {
69+
if (const bool.fromEnvironment('ENABLE_FLUTTER_DRIVER')) {
70+
enableFlutterDriverExtension();
71+
}
72+
runApp(const MyApp());
73+
}
74+
```
75+
- [ ] 3. Instruct the user to launch the app with: `flutter run -d <device-id> --dart-define=ENABLE_FLUTTER_DRIVER=true`.
76+
- [ ] 4. Use the `dtd` tool to discover the app and `flutter_driver_command` to drive its UI.
77+
- [ ] 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.
78+
79+
## Examples
80+
81+
### Scenario: Adding a Package and Scaffolding UI
82+
83+
**Input:** "Add a line chart to map user scores over time."
84+
85+
**Execution Steps:**
86+
1. Execute `pub_dev_search` with query "line chart".
87+
2. Identify `fl_chart` as the optimal package.
88+
3. Add dependency to `pubspec.yaml`.
89+
4. Generate the widget code using `fl_chart` boilerplate.
90+
5. Insert the widget into the target UI file.
91+
6. Trigger `hot_reload`.
92+
7. Run `get_runtime_errors` to ensure no missing constraints or syntax errors exist.
93+
94+
### Scenario: Proactive Hot Reloading
95+
96+
**Input:** "Change the primary button color to blue and increase the padding to 16."
97+
98+
**Execution Steps:**
99+
1. Locate the target `ElevatedButton` or `Container` in the Dart code.
100+
2. Update `style: ElevatedButton.styleFrom(backgroundColor: Colors.blue)` and `padding: EdgeInsets.all(16)`.
101+
3. Save the file.
102+
4. Immediately execute `hot_reload` using the active `appUri`.
103+
5. Confirm successful reload via tool output.

0 commit comments

Comments
 (0)