a2ui-migration
/a2ui-migration
Migruje aplikację, renderer lub katalog korzystający z A2UI do nowszej wersji SDK lub protokołu, w tym zmiany ładunków.
- Autor
- a2ui-project ↗
- Repozytorium
- a2ui ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Migruje aplikację, renderer lub katalog korzystający z A2UI do nowszej wersji SDK lub protokołu, w tym zmiany ładunków.
Oryginalny opis (EN)
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.
Jak działa
- Step 1: identify the language and the source SDK
- Step 2: identify the wire protocol version
- Step 3: fix the target
- Step 4: route to a case guide
- Generic procedure
- Migrating a package you do not own
- Adding a case
Podgląd SKILL.md
---
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.
---
# 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; the
v1.0 catalog files live under `catalogs/<name>/v1/`, but their ids keep the
`specification/v1_0` 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`](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](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.
Pliki w paczce (2)
- SKILL.md 14 KB
- references/dart_genui_to_1_0.md 255 KB
Wersje
W bazie nie ma innych skilli o nazwie a2ui-migration.
Migawka bazy z 13.11.2026 · wersja paczki 0af337df0f90 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100flutter-genui
Obsługuje Flutter GenUI SDK, czyli konwersacyjny UI sterowany AI z protokołem A2UI: renderery, katalogi widgetów, orkiestracja rozmowy, wiązanie DataModel i strumienie SSE. - 100integrate-genui-firebase
Integruje pakiet genui z Firebase AI Logic i uruchamia prostą rozmowę z modelem. - 100upgrade
Prowadzi aktualizację Backpex do nowszej wersji, obsługuje zmiany łamiące zgodność i wyjaśnia, co się zmieniło między wersjami. - 100ha-migration
Prowadzi aktualizację integracji Home Assistant do nowszej wersji: migrację wersji wpisów konfiguracji i poprawki przestarzałych elementów. - 90a2ui-protocols
Projektuje i egzekwuje protokoły komunikacji między agentem a interfejsem użytkownika, np. przy wdrażaniu A2UI lub budowie genUI. - 100genui-helper
Pomaga w pracy z repozytorium GenUI: przepływy pracy, uruchamianie testów, tworzenie komponentów, odnośniki do A2UI i Dart oraz standardy repozytorium.