upgrade-agent-native
/upgrade-agent-native
Doprowadza starszą aplikację lub przestrzeń Agent-Native do aktualnej wersji, naprawia nieudane aktualizacje i odradza łatanie rdzenia.
- Autor
- builderio ↗
- Repozytorium
- agent-native ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 27.10.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
Doprowadza starszą aplikację lub przestrzeń Agent-Native do aktualnej wersji, naprawia nieudane aktualizacje i odradza łatanie rdzenia.
Oryginalny opis (EN)
Bring an older Agent-Native app or workspace current. Use when updating @agent-native/core, fixing a broken upgrade, or when tempted to patch or override core/dispatch packages to make an old branch run.
Jak działa
- Rule
- Why
- How
- Don't
- Related Skills
Podgląd SKILL.md
---
name: upgrade-agent-native
description: >-
Bring an older Agent-Native app or workspace current. Use when updating
@agent-native/core, fixing a broken upgrade, or when tempted to patch or
override core/dispatch packages to make an old branch run.
scope: dev
metadata:
internal: true
---
# Upgrade Agent-Native
## Rule
When an older Agent-Native app/branch needs to run on current packages, use
`agent-native upgrade`. Never "fix" upgrade breakage with
`pnpm patch`, `pnpm patch-commit`, `pnpm.patchedDependencies`,
`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patch artifacts,
or edits under `node_modules/@agent-native/*` — especially not against
`@agent-native/core` or `@agent-native/dispatch`.
## Why
Agents often respond to a failed core bump by inventing framework patches and
dispatch behavior overrides. That hides the real app-level break, drifts from
upstream, and makes the next upgrade worse. The supported path is bump →
install → refresh scaffold skills → verify, then fix **app** code only.
## How
For the Core 0.198.0 package and import migration, follow the
[Core 0.198.0 upgrade runbook](../../../packages/core/docs/content/upgrading-core-ui.mdx).
It covers the preview and apply commands, Toolkit and optional peer packages,
codemod limits, and a symbol-level path map.
1. **Preview migration codemods first**
```bash
npx @agent-native/core@0.198.0 upgrade --codemods --dry-run
```
`--dry-run` previews the diff without writing. Do not manually edit imports
before applying the codemod; the migration manifest is the source of truth
for renamed specifiers and symbols.
2. **Apply the reviewed upgrade and codemods**
```bash
npx @agent-native/core@0.198.0 upgrade --codemods
```
Use the versioned CLI while the app still has Core 0.196 or another older
Core version: its local CLI carries an older migration manifest. After Core
0.198.0 is installed, `npx agent-native upgrade --codemods` (or
`pnpm exec agent-native upgrade --codemods` from an already-installed CLI)
uses the matching manifest. Either invocation applies supported codemods and
runs the upgrade, including dependency installation, scaffold skill refresh,
and typecheck when available. Do not run a second upgrade command just to
apply the codemods.
Afterward, run `npx agent-native doctor` from the app root. Its default
`migration-manifest` and `feature-dependencies` checks report stale imports
and missing optional peers detected from local settings. Confirm remote
deployment settings separately because Doctor cannot inspect them.
What it does:
- Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
- Rewrites non-local `@agent-native/*` dependency pins to `latest`
- Runs the package manager install
- Rewrites those pins to the exact versions the install resolved, so the
committed manifest names one release instead of re-resolving next install
- Runs `skills update scaffold --project`
- Runs `typecheck` when the project has that script
3. **Pull upstream template changes (optional, separate from the bump)**
`agent-native upgrade` moves package versions. It never touches files that
were copied out of a template at scaffold time, so template fixes and
improvements do not arrive with a bump.
```bash
agent-native template status # recorded ref vs latest, drift counts
agent-native template diff # what upstream changed, read-only
agent-native template sync # 3-way merge it into the app
```
`sync` defaults to the ref matching the installed `@agent-native/core`, so
run it after `upgrade`. It merges per file against a pristine baseline
stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
did not touch are left alone, and real collisions get conflict markers.
After resolving markers, run `agent-native template accept` — the baseline
deliberately does not advance past an unresolved merge.
Apps scaffolded before provenance existed have no baseline. Create one
with `agent-native template baseline` before the first sync.
4. **If upgrade or typecheck fails**
- Read the concrete error
- Fix **app** source, actions, config, or env — not framework packages
- Re-run `agent-native upgrade` or `pnpm typecheck`
- Stop and ask the user if you cannot fix the app-level error
Intentional app-level UI customization is a separate workflow. Read
`customizing-agent-native` when the product needs to own a selectively
copied component; do not use that path to reproduce framework runtime
behavior or hide version skew.
5. **Dry-run / partial runs**
```bash
agent-native upgrade --dry-run
agent-native upgrade --skip-verify
agent-native upgrade --skip-install # package.json bumps only
agent-native doctor --only migration-manifest
```
`migration-manifest` has no opt-out. Run it in CI before upgrading to find
imports that will break, then use `npx @agent-native/core@latest upgrade --codemods`
to preview the supported rewrite.
## Don't
- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
`patchedDependencies` for any `@agent-native/*` package
- Don't run `pnpm patch` or `pnpm patch-commit`, or commit files under
`patches/`, for any dependency
- Don't edit `node_modules/@agent-native/core` or
`node_modules/@agent-native/dispatch`
- Don't invent local "dispatch behavior" shims to paper over version skew
- Don't keep iterating with more framework patches after a failed install
- Don't skip `skills update scaffold --project` after a core bump (the
upgrade command does this for you)
## Related Skills
- **self-modifying-code** — Tier 4: framework packages are off limits
- **agent-native-docs** — version-matched docs after the bump
- **customizing-agent-native** — intentional app-owned UI copies, not upgrade patches
- **portability** — keep app code provider-agnostic across upgrades
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · builderio/agent-native | 100 | MIT |
| builderio/agent-native | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 17ab39a379cb (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
- 100multi-app-workspace
Opisuje, jak zbudować lub rozszerzyć wieloaplikacyjną przestrzeń roboczą Agent-Native: kształt monorepo, płaszczyzna sterowania Dispatch, aplikacja-powłoka i wspólny pakiet. - 100update
Doprowadza cały projekt do najnowszych wersji narzędzi i pakietów, pyta tylko o decyzje i kończy pull requestem. - 100upgrade-react-native
Prowadzi podnoszenie react-native do nowszej wersji, obejmując zmiany w projektach natywnych Android i iOS oraz łamiące zmiany. - 100koan-upgrade
Audytuje, planuje i migruje starszą aplikację Koan do bieżącej wersji, zachowując obserwowalne kontrakty i zatrzymując się, gdy nie da się wykazać zamiennika. - 100upgrades
Podnosi React Native, włącza New Architecture i utrzymuje w zgodzie natywne zależności, przy aktualizacji modułów natywnych. - 100react-native-web-core
Obejmuje podstawy React Native Web: koncepcje, komponenty i wzorce wieloplatformowe przy budowie aplikacji webowych.