Przejdź do treści
Biblioteka skilli
Projektowanie i UX · Konwersja i formaty

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.

Repozytorium
a2ui ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

  1. Step 1: identify the language and the source SDK
  2. Step 2: identify the wire protocol version
  3. Step 3: fix the target
  4. Step 4: route to a case guide
  5. Generic procedure
  6. Migrating a package you do not own
  7. Adding a case
Sekcje z nagłówków SKILL.md, w oryginale · 172 linii, 1 489 słów
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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.