The abyss-core-migration skill migrates create-abyss-app workspaces off @uhg-abyss/core and onto standard tooling. It handles web (Next.js), API (esbuild or webpack), and Parcels/Workshop products in a single automated pass.

The skill removes Abyss CLI and shared config coupling. It does not touch @uhg-abyss/web, @uhg-abyss/api, or @uhg-abyss/parcels — application code that legitimately depends on those packages is left untouched.

Tip

We recommend using Claude Sonnet 4.6 or higher for this skill.

Why migrate off @uhg-abyss/core

@uhg-abyss/core acts as a coupling layer between your project and the Abyss CLI — it owns your build scripts, wraps your config files, and manages environment variable injection at runtime. Migrating off it has several concrete benefits:

• Faster build and dev tooling — the migration targets Next.js 16 with Turbopack for web, esbuild for API, and Vite for Parcels. All three are meaningfully faster than the webpack-based pipeline @uhg-abyss/core ran previously, with esbuild and Vite also carrying a smaller dependency footprint
• Direct control over your toolchain — build configs are owned by your project, not buried inside a shared package. The customizations @uhg-abyss/core applied to the web build pipeline have been a recurring source of regressions and maintenance complexity; owning your config directly means changes are explicit, reviewable, and scoped to your project. Each tool can be upgraded independently on its own schedule
• Visible environment variable handling — the ABYSS_ENV_CONFIG runtime injection is replaced by standard .env.* files, making it clear exactly which values are available, when they're loaded, and whether they're browser-visible
• Independent security updates — because Next.js and other build dependencies are now direct dependencies of your project, your team can apply security patches immediately without waiting on an @uhg-abyss/core release to ship them
• Cleaner upgrade path — nothing in your CI or deployment scripts depends on the Abyss CLI being present, so future framework upgrades don't require coordinating with @uhg-abyss/core

Note

@uhg-abyss/core is planned for deprecation in a future release. Teams that migrate now will be ahead of that transition when it arrives.

What the skill does

The skill runs an 8-phase workflow. Phases 1–7 always execute; Phase 8 is optional.

Phase	Name	Description
1	Detection	Scans the workspace and summarizes all detected products, configs, and CLI commands before touching any files
2	Decisions	Collects build tool choices (API: esbuild or webpack; Parcels: Vite or webpack) in a single gate before any files are edited
3	Root migration	Removes @uhg-abyss/core from every package.json, inlines ESLint/TypeScript/Prettier configs, runs a clean install
4	Web migration	Migrates the Next.js product — replaces config helpers, installs dependencies, runs lint → build → dev
5	API migration	Migrates the API product using the chosen build tool, runs lint → build → dev
6	Parcels migration	Migrates the Parcels/Workshop product (Storybook + Vite or webpack), runs build → dev
7	Cleanup & handoff	Verifies @uhg-abyss/core is fully removed, delivers per-product environment variable notes
8	Deployment review (optional)	Scans CI/CD workflows, Dockerfiles, and deploy scripts for abyss CLI commands and updates them

Supported product types

Product	Framework	Supported build paths
Web	Next.js	Next.js native (next dev / next build / next start)
API	Node.js server	esbuild, webpack (current)
Parcels / Workshop	Storybook	Vite, webpack (current)

A workspace may contain any combination of these products — the skill handles all of them in a single migration pass.

Environment variable handling

Each product type replaces the Abyss CLI's runtime environment injection with direct .env file loading.

Web

The Abyss CLI previously injected an ABYSS_ENV_CONFIG JSON blob into the page at runtime. After migration, Next.js manages environment variables directly.

• Values destined for the browser must be prefixed with NEXT_PUBLIC_ and are baked into the JS bundle at build time
• Values without the prefix are only available in server-side Next.js code (API routes, getServerSideProps)
• The .abyss/environments.json blocks map to Next.js .env.* filenames:

environments.json block	Next.js file	When loaded
"env"	.env	Always (base values)
"env.local"	.env.development.local	next dev only, gitignored
"env.dev"	.env.development	next dev (NODE_ENV=development)
"env.test"	.env.test	NODE_ENV=test
"env.stage"	.env.stage	Loaded explicitly by build:stage via dotenv-cli
"env.prod"	.env.production	next build / next start (NODE_ENV=production)

API

The Abyss CLI previously selected the active environment block via abyss dev -e stage. After migration, a server-node.js entry point calls dotenv directly before any application code runs.

• All values are server-side only — no NEXT_PUBLIC_ prefix needed
• APP_ENV selects the override file at runtime: APP_ENV=stage node build/server.js
• The .abyss/environments.json blocks map to .env.* files loaded in this order:

environments.json block	File	When loaded
"env"	.env	Always (base values)
"env.local"	.env.local	Always, gitignored (local overrides)
"env.dev"	.env.dev	When APP_ENV=dev
"env.stage"	.env.stage	When APP_ENV=stage
"env.prod"	.env.prod	When APP_ENV=prod

Parcels

The Abyss CLI previously constructed the ABYSS_ENV_CONFIG blob from environments.json and injected it into the bundle. After migration, scripts/build.js replicates this behavior directly — it reads .env and .env.${APP_ENV}, constructs the same ABYSS_ENV_CONFIG shape, and bakes it into the Vite or webpack build.

• The runtime behavior of config() in the host app is unchanged — Parcels consumers continue reading values the same way
• APP_ENV selects the overlay: APP_ENV=prod node scripts/build.js

Prerequisites

Before installing this skill, ensure you have the Abyss CLI set up properly:

npx @uhg-abyss/cli -v

If the command fails, refer to the CLI Setup Guide for installation instructions.

Installation

Install the skill using the Abyss CLI:

npx @uhg-abyss/cli skills add abyss-core-migration

To verify the skill was installed successfully:

npx @uhg-abyss/cli skills list

Example prompts

Once installed, you can use prompts like these with this skill:

• "Migrate this project off @uhg-abyss/core"
• "Run the core migration skill on the monorepo"
• "Replace the abyss-dev and abyss-build commands with standard tooling"
• "Remove @uhg-abyss/web/tools/config from my Next.js app"
• "What would the core migration change in this repo before I commit to anything?"
• "Migrate only the web product off @uhg-abyss/core"

Additional context

A migration-session-log.md is created in your project root at the start of the session and updated throughout. Review it at the end for a plain-language summary of every file touched and any findings worth following up on.