How do I install the Upgrade Agent Native skill?

Run npx skillmds@latest add builderio/upgrade-agent-native-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Upgrade Agent Native safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Upgrade Agent Native?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Upgrade Agent Native free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Upgrade Agent Native?

Builder.io (@builderio) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Upgrade Agent Native by builderio — Agent Skill

Name: Upgrade Agent Native
Author: Builder.io

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.

Builder.io 6064016 2.8 KB Updated Sep 17, 2026 3.4k repo stars

File contents

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

Doctor first (optional but recommended)
```
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.
Run the upgrade
```
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
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

Dry-run / partial runs

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

---name: upgrade-agent-native-2description: 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.---# Upgrade Agent-Native## RuleWhen 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, oredits under `node_modules/@agent-native/*` — especially not against`@agent-native/core` or `@agent-native/dispatch`.## WhyAgents often respond to a failed core bump by inventing framework patches anddispatch behavior overrides. That hides the real app-level break, drifts fromupstream, and makes the next upgrade worse. The supported path is bump →install → refresh scaffold skills → verify, then fix **app** code only.## How1. **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 script3. **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 error4. **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

Frequently asked questions