From ed42a3e6744a84ac0f8bd9169a93f008d5d340b5 Mon Sep 17 00:00:00 2001 From: Andrew Brogdon Date: Mon, 16 Mar 2026 13:48:46 -0400 Subject: [PATCH 1/6] Adding two skills for genui --- .../genui/skills/create-catalog-item/SKILL.md | 125 +++++++++++++++ .../skills/integrate-genui-firebase/SKILL.md | 151 ++++++++++++++++++ 2 files changed, 276 insertions(+) create mode 100644 packages/genui/skills/create-catalog-item/SKILL.md create mode 100644 packages/genui/skills/integrate-genui-firebase/SKILL.md diff --git a/packages/genui/skills/create-catalog-item/SKILL.md b/packages/genui/skills/create-catalog-item/SKILL.md new file mode 100644 index 000000000..ed13c1ff9 --- /dev/null +++ b/packages/genui/skills/create-catalog-item/SKILL.md @@ -0,0 +1,125 @@ +--- +name: create-catalog-item +description: Use this skill when the user asks to create a new CatalogItem, data class, and/or widget class based on a JSON Schema definition in an application that uses Flutter's `genui` package. +--- + +# Create CatalogItem + +## Goal +To correctly implement a GenUI CatalogItem based on a provided json_schema_builder Schema, including its corresponding data class, top-level function, and Widget class. This ensures the AI model can properly generate and interact with the UI component. + +## Instructions +When tasked with creating a CatalogItem from a `Schema`, follow these steps: + +1. **Create the Data Class**: + - Name it `_Data` (e.g., if schema is `myCardSchema`, data class is `_MyCardData`). + - Add final fields for each property defined in the schema. + - Create a `factory _Data.fromJson(Map json)` method. + - Use a `try-catch` block to parse the properties and return a new instance. + - Cast each property from the `json` map to its expected type, e.g., `title: json['title'] as String,` or `action: json['action'] as JsonMap?,`. + - Throw an `Exception('Invalid JSON for _Data')` in the `catch` block if an error occurs. + +2. **Create the CatalogItem Top-Level Function**: + - Name it identical to the schema name but without the "Schema" suffix (e.g., `myCard` for `myCardSchema`). + - Declare as a `final CatalogItem`. + - Set `name` to the capitalized version of the name (e.g., `'MyCard'`). + - Set `dataSchema` to the provided schema. + - Implement the `widgetBuilder: (itemContext)`: + - Cast `itemContext.data` to `Map`. + - Parse the data using the data class `fromJson` method: `_Data.fromJson(json)`. + - Return the corresponding Widget class and pass the required data. + - If the schema includes an action callback (like `onCompleted`), implement it here. You must parse the action context using `resolveContext` and dispatch an event using `itemContext.dispatchEvent(...)`. + +3. **Create the Widget Class**: + - Name it `_` (e.g., `_MyCard`). + - Inherit from `StatelessWidget` or `StatefulWidget` depending on state requirements. + - Add the Data Class as a required property (e.g., `final _Data data;`). + - Add any required callback properties (e.g., `final void Function(int) onCompleted;`). + - Implement the `build` method using Flutter Material components (e.g., Card, Column, Text). Make sure each data field in the data class is displayed, and that actions are represented by buttons or other interactive elements. + +## Examples +### Input Schema +```dart +final basicCardSchema = S.object( + properties: { + 'component': S.string(enumValues: ['BasicCard']), + 'title': S.string(), + 'action': A2uiSchemas.action(), + }, + required: ['title'], +); +``` + +### Expected Output +```dart +class _BasicCardData { + final String title; + final JsonMap? action; + + _BasicCardData({required this.title, this.action}); + + factory _BasicCardData.fromJson(Map json) { + try { + return _BasicCardData( + title: json['title'] as String, + action: json['action'] as JsonMap?, + ); + } catch (_) { + throw Exception('Invalid JSON for _BasicCardData'); + } + } +} + +final basicCard = CatalogItem( + name: 'BasicCard', + dataSchema: basicCardSchema, + widgetBuilder: (itemContext) { + final json = itemContext.data as Map; + final data = _BasicCardData.fromJson(json); + + return _BasicCard( + data: data, + onTap: () async { + final action = data.action; + if (action == null) return; + final event = action['event'] as JsonMap?; + final name = (event?['name'] as String?) ?? ''; + final JsonMap contextDefinition = + (event?['context'] as JsonMap?) ?? {}; + final JsonMap resolvedContext = await resolveContext( + itemContext.dataContext, + contextDefinition, + ); + itemContext.dispatchEvent( + UserActionEvent( + name: name, + sourceComponentId: itemContext.id, + context: resolvedContext, + ), + ); + } + ); + }, +); + +class _BasicCard extends StatelessWidget { + final _BasicCardData data; + final VoidCallback onTap; + + const _BasicCard({super.key, required this.data, required this.onTap}); + + @override + Widget build(BuildContext context) { + return Card( + child: ListTile( + title: Text(data.title), + onTap: onTap, + ), + ); + } +} +``` + +## Constraints +- Ensure proper use of `try-catch` blocks and type casting when parsing JSON in `fromJson`. +- Make sure action resolution accurately fetches variables via `resolveContext` and uses `itemContext.dispatchEvent` when actions are present in the Schema. diff --git a/packages/genui/skills/integrate-genui-firebase/SKILL.md b/packages/genui/skills/integrate-genui-firebase/SKILL.md new file mode 100644 index 000000000..2e0125937 --- /dev/null +++ b/packages/genui/skills/integrate-genui-firebase/SKILL.md @@ -0,0 +1,151 @@ +--- +name: integrate-genui-firebase +description: Use this skill when the user asks to integrate the genui package and get a simple conversation going with Firebase AI Logic. +--- + +# Integrate GenUI with Firebase AI Logic + +## Goal +To successfully integrate the `genui` package into a Flutter app and set up a basic conversational agent using Firebase AI Logic. This skill assumes Firebase AI Logic is already set up and working in the project. + +## Instructions +When tasked with integrating `genui` and starting a simple conversation, follow these steps: + +1. **Verify Firebase Setup:** + Ensure `firebase_core` and `firebase_ai` are available in `pubspec.yaml`. + Verify that `Firebase.initializeApp` is called in the `main()` function: + ```dart + WidgetsFlutterBinding.ensureInitialized(); + await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform); + ``` + +2. **Add GenUI Package:** + Add `genui` to the `pubspec.yaml` dependencies. + +3. **Import Required Libraries:** + Import `genui` and hide `TextPart` so it doesn't conflict with other packages, then import it again with an alias: + ```dart + import 'package:genui/genui.dart' hide TextPart; + import 'package:genui/genui.dart' as genui; + ``` + +4. **Configure Basic Logging:** + At the beginning of the `main()` function, configure GenUI logging: + ```dart + configureLogging( + logCallback: (level, msg) => debugPrint('GenUI $level: $msg'), + ); + ``` + +5. **Create Model and Chat Session:** + Initialize the generative model and start a chat session. + ```dart + final model = FirebaseAI.googleAI().generativeModel( + model: 'gemini-3-flash-preview', + ); + final _chatSession = model.startChat(); + ``` + +6. **Identify Target StatefulWidget:** + **STOP AND ASK THE USER IF UNCLEAR:** This integration requires a `StatefulWidget` to hold the references to GenUI controllers (`SurfaceController`, `A2uiTransportAdapter`, and `Conversation`). Identify which `StatefulWidget` to use in the application. If you are unsure which widget should hold this state, ask the user before proceeding. + +7. **Wire up GenUI Controllers inside State:** + Inside your identified `State` class, instantiate `SurfaceController`, `A2uiTransportAdapter`, and `Conversation`: + ```dart + final catalog = BasicCatalogItems.asCatalog(); // Optionally inject custom CatalogItems + final _controller = SurfaceController(catalogs: [catalog]); + final _transport = A2uiTransportAdapter(onSend: _sendAndReceive); + final _conversation = Conversation( + controller: _controller, + transport: _transport, + ); + ``` + +8. **Implement the `_sendAndReceive` Method:** + Create a method to take messages from the transport adapter, send them to Firebase, and feed the AI's response back to the transport. + ```dart + Future _sendAndReceive(ChatMessage msg) async { + final buffer = StringBuffer(); + + for (final part in msg.parts) { + if (part.isUiInteractionPart) { + buffer.write(part.asUiInteractionPart!.interaction); + } else if (part is genui.TextPart) { + buffer.write(part.text); + } + } + + if (buffer.isEmpty) return; + + final text = buffer.toString(); + final response = await _chatSession.sendMessage(Content.text(text)); + + if (response.text?.isNotEmpty ?? false) { + _transport.addChunk(response.text!); + } + } + ``` + +9. **Listen to Conversation Events:** + Create stubbed-out methods in your State class for each event type, including DartDoc comments explaining their required behavior. + ```dart + /// Updates state to include the new [surfaceId] so a new `Surface` widget can be built. + void _onSurfaceAdded(String surfaceId) { + // TODO: Implement state update to add surfaceId + } + + /// Updates state to remove the [surfaceId] so its `Surface` widget is no longer built. + void _onSurfaceRemoved(String surfaceId) { + // TODO: Implement state update to remove surfaceId + } + + /// Handles displaying raw text content received from the AI to the user. + void _onContentReceived(String text) { + // TODO: Implement displaying the received text + } + + /// Handles errors that occur during the conversation appropriately. + void _onError(Object error) { + // TODO: Implement error handling + } + ``` + + Subscribe to the `_conversation.events` to track when UI surfaces or chat messages arrive, dispatching them to the appropriate stubbed out methods: + ```dart + _conversation.events.listen((event) { + switch (event) { + case ConversationSurfaceAdded added: + _onSurfaceAdded(added.surfaceId); + case ConversationSurfaceRemoved removed: + _onSurfaceRemoved(removed.surfaceId); + case ConversationContentReceived content: + _onContentReceived(content.text); + case ConversationError error: + _onError(error.error); + default: + } + }); + ``` + +10. **Initialize System Prompt:** + Use `PromptBuilder` to give the AI basic instructions, then send it as a system message. + ```dart + final promptBuilder = PromptBuilder.chat( + catalog: catalog, + instructions: 'You are a helpful assistant. Respond to messages in a chatty way.', + ); + _conversation.sendRequest(ChatMessage.system(promptBuilder.systemPrompt)); + ``` + +11. **Display Surfaces:** + In your Flutter `build()` method, use the `Surface` widget wherever you need to render GenUI widgets using the `surfaceIds` you collected in step 9. + ```dart + Surface(surfaceContext: _controller.contextFor(surfaceId)); + ``` + +12. **Ask User for Input Preferences:** + **STOP AND ASK THE USER:** Ask the user for clarification on what UI elements should be used for user input. Explain that a `TextField` and `ElevatedButton` are good defaults, but you should not assume they want those exact widgets unless they clarify. + +## Constraints +- Do not make assumptions about user input UI elements; see step 12. +- Make sure to properly clean up GenUI controllers (`_transport.dispose()`, `_controller.dispose()`) inside the widget's `dispose()` method. From 980e58fd632403673639aa7868bdb5c2ac5e11a9 Mon Sep 17 00:00:00 2001 From: Andrew Brogdon Date: Mon, 16 Mar 2026 14:52:10 -0400 Subject: [PATCH 2/6] Adding README blurb. --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index 3d956ba44..3146eb63a 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,14 @@ The Flutter Gen UI SDK currently supports A2UI v0.9. See the [genui getting started guide](packages/genui/README.md#getting-started-with-genui). +## Skills + +This repo contains [skill files](packages/genui/skills/) for developers building with agentic coding tools. They can be copied directly into an agent's preferred location or installed using the [`skills`](https://www.npmjs.com/package/skills) package: + +```bash +npx skills add https://github.com/redbrogdon/genui/tree/main/packages/genui/skills +``` + ## Constraints This repo requires Flutter version >=3.35.7. From 274dd75209feca77b9cf43ba63f47c3850c06ff7 Mon Sep 17 00:00:00 2001 From: Andrew Brogdon <969662+redbrogdon@users.noreply.github.com> Date: Mon, 16 Mar 2026 15:26:13 -0400 Subject: [PATCH 3/6] Accepting Gemini review comments. Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- packages/genui/skills/create-catalog-item/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/genui/skills/create-catalog-item/SKILL.md b/packages/genui/skills/create-catalog-item/SKILL.md index ed13c1ff9..d39a45231 100644 --- a/packages/genui/skills/create-catalog-item/SKILL.md +++ b/packages/genui/skills/create-catalog-item/SKILL.md @@ -83,7 +83,8 @@ final basicCard = CatalogItem( final action = data.action; if (action == null) return; final event = action['event'] as JsonMap?; - final name = (event?['name'] as String?) ?? ''; + final name = event?['name'] as String?; + if (name == null || name.isEmpty) return; final JsonMap contextDefinition = (event?['context'] as JsonMap?) ?? {}; final JsonMap resolvedContext = await resolveContext( From e08c8044b08d94d67b728d1942ac3ba91e321dc5 Mon Sep 17 00:00:00 2001 From: Andrew Brogdon <969662+redbrogdon@users.noreply.github.com> Date: Mon, 16 Mar 2026 15:26:34 -0400 Subject: [PATCH 4/6] Accepting further review from Gemini. Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- packages/genui/skills/create-catalog-item/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/genui/skills/create-catalog-item/SKILL.md b/packages/genui/skills/create-catalog-item/SKILL.md index d39a45231..7609828f9 100644 --- a/packages/genui/skills/create-catalog-item/SKILL.md +++ b/packages/genui/skills/create-catalog-item/SKILL.md @@ -64,8 +64,8 @@ class _BasicCardData { title: json['title'] as String, action: json['action'] as JsonMap?, ); - } catch (_) { - throw Exception('Invalid JSON for _BasicCardData'); + } catch (e) { + throw Exception('Invalid JSON for _BasicCardData: $e'); } } } From 98b1edb650ea5fcc01722b6991332caccf1a1c37 Mon Sep 17 00:00:00 2001 From: Andrew Brogdon Date: Mon, 16 Mar 2026 15:22:07 -0400 Subject: [PATCH 5/6] Fixing skill URL. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3146eb63a..f8ca62ce3 100644 --- a/README.md +++ b/README.md @@ -129,7 +129,7 @@ See the [genui getting started guide](packages/genui/README.md#getting-started-w This repo contains [skill files](packages/genui/skills/) for developers building with agentic coding tools. They can be copied directly into an agent's preferred location or installed using the [`skills`](https://www.npmjs.com/package/skills) package: ```bash -npx skills add https://github.com/redbrogdon/genui/tree/main/packages/genui/skills +npx skills add https://github.com/flutter/genui/tree/main/packages/genui/skills ``` ## Constraints From 8f1c4f459c3a55c2a225c992319f818bb90ebaef Mon Sep 17 00:00:00 2001 From: Andrew Brogdon Date: Mon, 16 Mar 2026 15:34:40 -0400 Subject: [PATCH 6/6] Fixing typo --- packages/genui/skills/create-catalog-item/SKILL.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/packages/genui/skills/create-catalog-item/SKILL.md b/packages/genui/skills/create-catalog-item/SKILL.md index 7609828f9..9cbf5b0ff 100644 --- a/packages/genui/skills/create-catalog-item/SKILL.md +++ b/packages/genui/skills/create-catalog-item/SKILL.md @@ -6,7 +6,7 @@ description: Use this skill when the user asks to create a new CatalogItem, data # Create CatalogItem ## Goal -To correctly implement a GenUI CatalogItem based on a provided json_schema_builder Schema, including its corresponding data class, top-level function, and Widget class. This ensures the AI model can properly generate and interact with the UI component. +To correctly implement a GenUI CatalogItem based on a provided json_schema_builder Schema, including its corresponding data class, CatalogItem instance, and Widget class. This ensures the AI model can properly generate and interact with the UI component. ## Instructions When tasked with creating a CatalogItem from a `Schema`, follow these steps: @@ -19,7 +19,7 @@ When tasked with creating a CatalogItem from a `Schema`, follow these steps: - Cast each property from the `json` map to its expected type, e.g., `title: json['title'] as String,` or `action: json['action'] as JsonMap?,`. - Throw an `Exception('Invalid JSON for _Data')` in the `catch` block if an error occurs. -2. **Create the CatalogItem Top-Level Function**: +2. **Create the CatalogItem Instance**: - Name it identical to the schema name but without the "Schema" suffix (e.g., `myCard` for `myCardSchema`). - Declare as a `final CatalogItem`. - Set `name` to the capitalized version of the name (e.g., `'MyCard'`). @@ -83,8 +83,7 @@ final basicCard = CatalogItem( final action = data.action; if (action == null) return; final event = action['event'] as JsonMap?; - final name = event?['name'] as String?; - if (name == null || name.isEmpty) return; + final name = (event?['name'] as String?) ?? ''; final JsonMap contextDefinition = (event?['context'] as JsonMap?) ?? {}; final JsonMap resolvedContext = await resolveContext(