---
name: a2ui-migration
description: >-
  Migrates an app, renderer, catalog or agent that uses A2UI (or a predecessor such as Flutter `genui`) to a newer SDK or protocol version. Use when a task mentions migrating, upgrading, porting or moving A2UI code between SDKs, packages or protocol versions (v0.8, v0.9, v0.9.1, v1.0), when a dependency such as `genui`, `a2ui_core`, `@a2ui/web_core`, `a2ui-core` or an A2UI Swift package needs a major bump, or when payloads or fixtures must change wire version. The skill first identifies the language, the source and the target, then routes to a case-specific guide where one exists.
title: a2ui-migration
canonical_url: https://skilld.dev/gh/a2ui-project/a2ui/a2ui-migration
last_updated: 2026-11-18T11:03:50.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/dart_genui_to_1_0.md](https://skilld.dev/api/skills-raw/a2ui-project/a2ui/a2ui-migration/references/dart_genui_to_1_0.md).
>
> If the user asked to install this Skill, run `npx skilld install a2ui-project/a2ui/a2ui-migration`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/a2ui-migration`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/a2ui-project/a2ui/a2ui-migration) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/a2ui-migration`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/a2ui-migration --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/a2ui-migration --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# A2UI migration

This skill is a router. It identifies what is being migrated and then sends
you to the guide for that case. A case is identified by three facts:

1. **Language / platform**: Dart (Flutter), TypeScript (Lit, Angular, React,
   web core), Python (agent SDKs, ADK, A2A), Swift, Kotlin.
2. **Source**: the SDK or package the code uses today and its version, and
   the protocol version it speaks on the wire.
3. **Target**: the SDK the code should use afterwards, and the protocol
   version it should speak.

Do not start editing before all three are written down. A migration that
changes the SDK and the wire version at the same time is two migrations;
split it when the agent and the renderer are not released together.

## Step 1: identify the language and the source SDK

Read the manifests in the repository, not just the file extensions:

| Manifest                                         | Dependency names to look for                                                                                          |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `pubspec.yaml`, Bazel `BUILD` with `dart_*`      | `genui`, `a2ui_core`, `a2ui_flutter`, `a2ui_agent`, `a2ui_cli`, `genai_primitives`                                    |
| `package.json`                                   | `@a2ui/web_core`, `@a2ui/lit`, `@a2ui/angular`, `@a2ui/react`, `@a2ui/markdown-it`, `@a2ui/agent`, `@a2ui/catalog-*`  |
| `pyproject.toml`, `requirements*.txt`, `uv.lock` | `a2ui-core`, `a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`, `a2ui-catalog-*`                                               |
| `Package.swift`                                  | `A2UISwiftCore`, `A2UISwiftUI`, `BasicCatalog`, `BasicCatalogSwiftUI` (products of this repository's `Package.swift`) |
| `build.gradle*`                                  | the legacy Kotlin agent SDK under `kotlin/agent_sdk_legacy/`                                                          |

Record the exact version constraint, and read that package's `CHANGELOG.md`
in this repository for the release line the code is on.

## Step 2: identify the wire protocol version

The SDK version does not always tell the protocol version; read the payloads
the code sends or expects (fixtures, goldens, prompts, transport code):

| Evidence in payloads                                                                                                                                       | Protocol |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `beginRendering`, `surfaceUpdate`, `dataModelUpdate` messages                                                                                              | v0.8     |
| `"version": "v0.9"` with `createSurface`, `updateComponents`, `updateDataModel`, `deleteSurface`; bindings as `{"path": ...}` and calls as `{"call": ...}` | v0.9     |
| `"version": "v0.9.1"`                                                                                                                                      | v0.9.1   |
| `"version": "1.0"`; bindings as `{"@path": ...}`, calls as `{"@call": ...}`; per-component `catalogId`; `callRendererFunction` / `callAgentFunction`       | v1.0     |

Other signs: catalog ids (`.../specification/v0_9/catalogs/basic/catalog.json`
is v0.9, `.../specification/v1_0/catalogs/basic/catalog.json` is v1.0; catalog
files live under `catalogs/`, but their ids keep the `specification/<version>`
path), the metadata keys for capabilities
(`a2uiClientCapabilities` is v0.9, `a2uiRendererCapabilities` is v1.0), and
the names of the schema directories a project validates against
(`specification/v0_9/json` versus `specification/v1_0/json`).

## Step 3: fix the target

Ask, or infer from the task, whether the target is a new SDK on the same
protocol version, a new protocol version on the same SDK, or both. When the
task does not say, prefer the smallest step: the current SDK's latest release
on the protocol version the agent already speaks. Record the target the same
way as the source.

## Step 4: route to a case guide

| Language | From                               | To                                                          | Guide                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dart     | `genui` 0.9.x / 0.10.x (A2UI v0.9) | `a2ui_core` + `a2ui_flutter` (+ `a2ui_agent`), v0.9 or v1.0 | [`references/dart_genui_to_1_0.md`](https://skilld.dev/api/skills-raw/a2ui-project/a2ui/a2ui-migration/references/dart_genui_to_1_0.md)                                                                                                                                                                                                                                                                     |
| any      | protocol v0.8                      | protocol v0.9                                               | [`specification/v0_9/docs/evolution_guide.md`](../../../specification/v0_9/docs/evolution_guide.md); Python payload converter [`samples/agent/adk/migrate_v08_to_v09.py`](../../../samples/agent/adk/migrate_v08_to_v09.py); Lit renderer example in [`typescript/renderers/lit/README.md`](../../../typescript/renderers/lit/README.md) |
| any      | protocol v0.9                      | protocol v0.9.1                                             | [`specification/v0_9_1/docs/evolution_guide.md`](../../../specification/v0_9_1/docs/evolution_guide.md)                                                                                                                                                                                                                                  |
| any      | protocol v0.9 / v0.9.1             | protocol v1.0                                               | [`specification/v1_0/docs/evolution_guide.md`](../../../specification/v1_0/docs/evolution_guide.md), then the SDK's `CHANGELOG.md`                                                                                                                                                                                                       |
| any      | an A2UI SDK release                | a later release of the same SDK                             | that package's `CHANGELOG.md` (`Breaking:` entries first), then the generic procedure below                                                                                                                                                                                                                                              |

When a row matches, read the guide in full and follow it. When no row
matches, follow the generic procedure and then add a case (see the end of
this file).

## Generic procedure

Use this when no case guide exists, and as the outer loop around a case
guide:

1. **Inventory.** List every file that imports or depends on the source SDK,
   every fixture or golden that holds payloads, and every prompt that
   describes the wire format to a model. Group them by the layer they touch:
   transport, renderer wiring, catalogs and components, functions, tests.
2. **Dependencies first.** Change the manifest, then make the project resolve
   dependencies. Do not edit source until the new packages are installed.
3. **One layer at a time.** Migrate transport, then renderer wiring, then
   catalogs and components, then functions, then tests. Compile after each
   layer; a layer that does not compile hides errors in the next one.
4. **Payloads and prompts.** Update fixtures, goldens and prompt text to the
   target wire version. Do not blanket-replace keys; the evolution guides
   list which positions change.
5. **Behavioral differences.** Read the target's behavior notes (a case guide
   has a section for them) and check each one against the app: error
   handling, validation strictness, unknown ids, ordering, markdown, theming.
6. **Verify.** Run the analyzer or type checker, unit and widget tests, and
   one manual round trip against the real agent with a surface that has an
   input and an action.
7. **Record.** Note in the change description which case was applied, which
   behavioral differences needed app changes, and anything the guide did not
   cover.

## Migrating a package you do not own

When the migration is a pull request to someone else's repository, such as a
package on pub.dev that depends on `genui`:

1. Read the repository's CI workflows, its task runner and local gate
   scripts, its agent instructions (`AGENTS.md`, `CLAUDE.md`,
   `.cursor/rules/` and the like), its `CONTRIBUTING.md` (some require a
   signed CLA before a PR is merged) and its commit and PR title conventions
   first (some repositories check PR titles against Conventional Commits;
   follow the history's language too). Run the CI steps locally before and
   after the change, including in examples and in every package of the
   repository that depends on the migrated one, even when CI skips them.
   Use the toolchain release CI uses. When the repository pins a toolchain
   release you cannot install, relax the pin only to run the checks, then
   restore it everywhere it is recorded.
2. Keep the package's name and public class names. Keep its API shape where
   the new SDK allows, and list each breaking change in its `CHANGELOG.md`
   under an `Unreleased` heading; leave the version number to the maintainer.
3. Update the README, examples and agent instructions that show the old
   SDK's API, so they do not teach code that no longer compiles.
4. Commit only the migration:
   - Include the manifests, the tracked lock files, and generated files
     that change because a dependency was added or dropped, such as plugin
     registrations.
   - Leave out edits that tools make on their own (configuration rewrites,
     lock changes that a plain install on a newer toolchain makes before
     any edit; mention those in the change description), unrelated
     generated changes, and generated files that hold local paths. In a
     repository without a complete ignore file, stage files by name.
   - When the change only removes dependencies, the lock loses exactly the
     packages that nothing else needs; check that a fresh resolve changes
     nothing more.
   - A lock resolved with a newer toolchain can pick releases that the
     project's own toolchain (CI, version files) cannot use. Check each new
     package against it, and hold back the ones it cannot use.
5. Keep the package's minimum language or SDK version even when the new
   dependencies need a newer one. The package manager already refuses a
   toolchain older than a dependency needs, while a higher bound can change
   language semantics or formatting across the whole package.
6. Read the APIs of the published SDK releases (in the package manager's
   cache), not this repository's sources, which may be ahead of the release.
7. Leave behavior the migration did not have to change as it is, including
   bugs you notice, and mention them in the change description instead.
8. In an app repository, update living docs (architecture notes, READMEs,
   comments in other languages) but leave decision records, specs and plans
   of their time as they are, and dated experiments outside the workspace
   and CI when the project's tooling says to. When the repository requires a decision
   record for a changed dependency, add one as proposed and leave the
   decision to the owner. When the agent side is in another language and
   the client translates its records to the wire version, keep that
   translation, so the agent and its stored data do not change.

A case guide lists what these rules mean on its platform; for Dart and
Flutter, see
[In a package you do not own](https://skilld.dev/api/skills-raw/a2ui-project/a2ui/a2ui-migration/references/dart_genui_to_1_0.md#in-a-package-you-do-not-own).

## Adding a case

When you migrate something this skill has no guide for, add one so the next
migration starts from it:

1. Create `references/<language>_<from>_to_<to>.md` next to this file, named
   like `references/dart_genui_to_1_0.md`.
2. Give it the same sections as the existing guide: scope and version
   assumptions, dependencies, a step per layer with before/after code,
   checklist, API mapping, recipes, and behavior changes.
3. Add a row to the table in Step 4.
4. Follow [`natural-writing`](../natural-writing/SKILL.md) and
   [`pr-hygiene`](../pr-hygiene/SKILL.md) for the text and the pull request.
