Skip to content
Skills Library
Programming · Conversion & formats

upgrade-agent-native

/upgrade-agent-native

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.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author 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.

How it works

  1. Rule
  2. Why
  3. How
  4. Don't
  5. Related Skills
Original SKILL.md headings · 78 lines, 337 words
SKILL.md preview
---
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.overrides`, `patchedDependencies`, `resolutions`, local patches, 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

1. **Doctor first (optional but recommended)**

   ```bash
   npx @agent-native/core@latest upgrade check
   ```

   This reports framework overrides/patches and pending `@agent-native/*`
   bumps. If overrides/patches are present, remove them before continuing.

2. **Run the upgrade**

   ```bash
   npx @agent-native/core@latest upgrade
   ```

   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
   `agent-native upgrade`.

   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
   - Runs `skills update scaffold --project`
   - Runs `typecheck` when the project has that script

3. **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

4. **Dry-run / partial runs**

   ```bash
   agent-native upgrade --dry-run
   agent-native upgrade --skip-verify
   agent-native upgrade --skip-install   # package.json bumps only
   ```

## Don't

- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
  `patchedDependencies` for any `@agent-native/*` package
- 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
- **portability** — keep app code provider-agnostic across upgrades

Versions

RepositoryScoreLicence
This page · builderio/agent-native100MIT
builderio/agent-native100MIT

Database snapshot: 13.11.2026 · package version a56b0c2fc269 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100multi-app-workspace
    How to build or extend a multi-app Agent-Native workspace — the monorepo shape, the Dispatch control plane, the shell app that fronts every other app, and the shared package. Use when the user asks for a workspace, a platform, a suite of apps, an app launcher or shell, a second…
  • 100update
    Bring a whole project to the latest of everything, now and then. Upgrade the tools, their settings and every package, big upgrades included, ask only about the ones that need the owner's call, prove the app still builds and works, and end in a pull request. Use when someone says…
  • 100upgrade-react-native
    Use when upgrading react-native to a newer version. Handles version bumps, native project changes (Android/iOS), dependency updates, and breaking change migration. Invoke with `/upgrade-react-native <version>`.
  • 100koan-upgrade
    Audit, plan, and migrate an older Koan application to current Koan. Use when an app resolves older Koan dependencies, uses removed Koan APIs, configuration, or composition, or the user requests a Koan framework-version migration. Preserve observable application contracts and…
  • 100upgrades
    Upgrade React Native, adopt the New Architecture, and keep native dependencies aligned. Use when bumping React Native, enabling the New Architecture, or updating a native module.
  • 100react-native-web-core
    Use when working with React Native Web projects. Provides core concepts, components, and cross-platform patterns for building web applications with React Native.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.