Add flutter-app-runtime skill for runtime inspection MCP tools

Add the `flutter-app-runtime` skill to provide runtime application discovery,
live widget inspection, layout/error diagnostics, and proactive hot reloading
via the Dart MCP server.

This skill provides the runtime management workflows referenced by the proactive
Flutter hot reload rule introduced in #228 (rules/flutter-app-runtime.md). While
the rule triggers upon `.dart` file modifications, this skill also equips agents
to handle non-edit observational queries about the running application without
falling back to static source code assumptions.

Key capabilities and workflows added:
- Live UI & Hierarchy Inspection: Query the live widget tree via `widget_inspector`
  (`get_widget_tree`), supporting `summaryOnly: false` to inspect exact immediate
  parent widgets and framework styling wrappers, and `summaryOnly: true` for user
  code structure.
- Layout Overflow & Error Diagnostics: Check for active `RenderFlex` overflows and
  framework exceptions using `get_runtime_errors` and inspect render box constraints.
- Proactive Hot Reload / Hot Restart: Execute `hot_reload` on UI modifications or
  `hot_restart` on foundational state/initialization changes, followed by
  verifying runtime stability.
- Application Discovery: Discover and connect to active instances via `dtd`
  (`listDtdUris`, `connect`, `listConnectedApps`) with clear fallback handling
  when no running app is connected.

Related:
- Companion rule: #228
- Supersedes: #221

Author: jwren

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 Dart MCP server tools (widget_inspector, dtd, get_runtime_errors, hot_reload, hot_restart) to inspect live widget trees, diagnose layout clipping and runtime errors, and execute proactive hot reloads. Use when answering questions about the active screen, inspecting widget structure, styling, or colors, checking for runtime overflows, debugging errors, or modifying UI widgets in a running app. | Inspect the active widget tree to check for layout clipping and tell me the immediate parent of the counter text |
 | [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,41 @@
     - 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 Dart MCP server tools (widget_inspector, dtd, get_runtime_errors, hot_reload, hot_restart) to inspect live widget trees, diagnose layout clipping and runtime errors, and execute proactive hot reloads. Use when answering questions about the active screen, inspecting widget structure, styling, or colors, checking for runtime overflows, debugging errors, or modifying UI widgets in a running app."
+  examplePrompt: "Inspect the active widget tree to check for layout clipping and tell me the immediate parent of the counter text"
+  instructions: |
+    This Skill enables interaction with running Dart and Flutter applications via the
+    Dart MCP server and Dart Tooling Daemon (DTD).
+
+    Pre-requisite:
+    The Dart and Flutter MCP server must be configured and active.
+
+    Core capabilities include:
+    - Application Discovery: Discover active instances and connect via DTD (`dtd` tool).
+    - Widget Inspection: Query live widget hierarchies, determine immediate parent widgets, inspect rendered properties, styles, and colors (`widget_inspector`).
+    - Error & Layout Diagnostics: Retrieve live runtime exceptions, identify RenderFlex overflows, and detect layout clipping on the active screen (`get_runtime_errors`).
+    - Hot Reload & Hot Restart: Proactively push visual changes (`hot_reload`) or reset application state when modifying state initialization (`hot_restart`).
+
+    Decision workflow:
+    1. Identify Targets: Use the `dtd` tool (via `listDtdUris`, `connect`, and `listConnectedApps`)
+       to discover and connect to running application instances in the current workspace. If no app
+       is running, inform the user immediately and fall back to static source code analysis if answering
+       inspection questions, or proceed with code edits if modifying files.
+    2. Live UI & Hierarchy Inspection: When answering questions about current screen appearance,
+       widget styling, colors, or parent-child hierarchy, execute `widget_inspector` with `command: "get_widget_tree"`.
+       Use `summaryOnly: false` to inspect the exact immediate parent widget or complete framework tree
+       including intermediate styling and layout widgets (e.g., DefaultTextStyle, Semantics, Padding).
+       Use `summaryOnly: true` for high-level user-defined widget summaries.
+    3. Runtime Error & Layout Overflow Diagnosis: When asked about layout issues, clipping, or errors on the
+       current screen size, execute `get_runtime_errors` to check for active RenderFlex overflows or exceptions.
+       Use `widget_inspector` to evaluate constraints and render box geometry.
+    4. Proactive Hot Reload & State Reset: Whenever edits are made to Flutter UI widgets or Dart code,
+       proactively trigger `hot_reload` across all active instances to maintain visual consistency.
+       If modifying foundational state, `initState`, or `main()`, trigger `hot_restart`.
+       Always call `get_runtime_errors` following a reload to verify zero new exceptions.
+  resources:
+    - https://docs.flutter.dev/ai/mcp-server
+    - https://docs.flutter.dev/ai/get-started
+    - https://docs.flutter.dev/tools/hot-reload

skills/flutter-app-runtime/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: flutter-app-runtime
+description: Interacts with running Dart and Flutter applications via Dart MCP server tools (widget_inspector, dtd, get_runtime_errors, hot_reload, hot_restart) to inspect live widget trees, diagnose layout clipping and runtime errors, and execute proactive hot reloads. Use when answering questions about the active screen, inspecting widget structure, styling, or colors, checking for runtime overflows, debugging errors, or modifying UI widgets in a running app.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Fri, 28 Aug 2026 22:38:31 GMT
+---
+# Interacting with Live Flutter Applications
+
+## Contents
+- [Prerequisites](#prerequisites)
+- [Application Discovery](#application-discovery)
+- [Live UI & Hierarchy Inspection](#live-ui--hierarchy-inspection)
+- [Error & Layout Diagnostics](#error--layout-diagnostics)
+- [Hot Reload & Hot Restart](#hot-reload--hot-restart)
+- [Task Progress Checklist](#task-progress-checklist)
+
+## Prerequisites
+Ensure the Dart and Flutter MCP server is configured and active. This skill relies on the Dart Tooling Daemon (DTD) and associated MCP tools to interact with running application instances.
+
+## Application Discovery
+Always verify active application instances before attempting live inspection or hot reloading.
+
+1. Execute the `dtd` tool using `listDtdUris` to find available daemon URIs.
+2. Use `connect` to establish a connection to the DTD.
+3. Use `listConnectedApps` to discover running application instances in the current workspace.
+4. **Conditional Fallback:** If no application is running, inform the user immediately. Fall back to static source code analysis for inspection questions, or proceed with standard file edits if modifying code.
+
+## Live UI & Hierarchy Inspection
+When answering questions about current screen appearance, widget styling, colors, or parent-child hierarchy, query the live widget tree.
+
+1. Execute the `widget_inspector` tool with `command: "get_widget_tree"`.
+2. **Conditional Detail Level:**
+   - If inspecting the exact immediate parent widget, intermediate styling, or layout widgets (e.g., `DefaultTextStyle`, `Semantics`, `Padding`), set `summaryOnly: false`.
+   - If generating high-level user-defined widget summaries, set `summaryOnly: true`.
+
+## Error & Layout Diagnostics
+When diagnosing layout issues, clipping, or errors on the current screen size, retrieve live runtime exceptions.
+
+1. Execute the `get_runtime_errors` tool to check for active `RenderFlex` overflows or exceptions.
+2. Execute the `widget_inspector` tool to evaluate constraints and render box geometry for the problematic widgets.
+3. Review the errors, apply the necessary layout fixes (e.g., wrapping in `Expanded`, `Flexible`, or `SingleChildScrollView`), and trigger a hot reload.
+
+## Hot Reload & Hot Restart
+Proactively push changes to the running application to maintain visual consistency and verify fixes. 
+
+**Conditional Reload Logic:**
+- **If modifying Flutter UI widgets or standard Dart code:** Trigger the `hot_reload` tool. This preserves application state and rebuilds the widget tree.
+- **If modifying foundational state, `initState()`, `main()`, global variables, or static fields:** Trigger the `hot_restart` tool. This resets the application state and re-executes initialization code.
+- **If modifying native code (Kotlin, Java, Swift, Objective-C):** Inform the user that a full manual restart is required. Hot reload/restart will not apply these changes.
+
+**Feedback Loop:**
+Always execute `get_runtime_errors` immediately following a `hot_reload` or `hot_restart` to verify that zero new exceptions were introduced. If errors are present, review the diagnostics, fix the code, and reload again.
+
+## Task Progress Checklist
+Copy and use this checklist to track progress during live application modification workflows:
+
+```markdown
+- [ ] Discover and connect to active application instances via `dtd`.
+- [ ] Inspect current UI state via `widget_inspector` (if applicable).
+- [ ] Implement code modifications.
+- [ ] Determine required reload type (Hot Reload vs. Hot Restart).
+- [ ] Execute `hot_reload` or `hot_restart`.
+- [ ] Run `get_runtime_errors` to verify zero new exceptions.
+- [ ] Fix any newly introduced errors and repeat the reload loop.
+```