← Explore all skills

MIGRATION / Effectful Technologies

Effect v3 to v4

Migrates Effect v3 to v4 by searching the generated reference one symbol at a time, and forbids a compatibility shim.

“Use this skill when migrating a codebase from Effect v3 to Effect v4, upgrading `effect` or any `@effect/*` package across the v3/v4 boundary.”

01 / THE REASONING

Why this made the selection.

  • package.json is fixed before the type-check, merged packages are removed, and every remaining Effect package shares one version.
  • The generated reference is searched, never read whole. A v3 compatibility shim, any, or a cast is forbidden, and a replacement that is not in the reference or the v4 source is not invented.

02 / THE REVIEW RECORD

What we actually inspected.

Source review has boundaries.
A clear record is more useful than a “safe” badge.

Material inspected

  • skills/effect-v3-to-v4/SKILL.md
  • LICENSE
  • skills/effect-v3-to-v4/SKILL.md compared with the previous review revision 2309e6f2: changes to the effect-smol note, the v4 source path, the reference size, the package list and the module-path rules; LICENSE unchanged.

Our findings

  • LICENSE is the MIT Licence with Copyright (c) 2023 Effectful Technologies Inc. There is no SPDX-License-Identifier line.
  • Lookup order is MIGRATION.md, a search of the generated reference, a topic guide, v4 source, then v3 source. The done condition is a clean type-check.
  • At this revision GA imports use paths such as effect/http, stability is declared by @stability JSDoc tags, and code written against a beta with effect/unstable/<module> imports drops the unstable segment; the skill says there are no compatibility exports for the old paths.

Not established by this review

  • No repository was cloned.
  • No type-check was run.
  • The generated migration guide was not opened.
  • Not executed: it was not installed or run.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

Add a skill to your workflow.

Upstream setup instructions ↗

DOCUMENTED COMMAND

npx skills add Effect-TS/skills/skills/effect-v3-to-v4

Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.

Optional: install the reviewed revision

Keeps the original source and installer version where recorded, while leaving your AI tools and installation scope for you to choose.

npx skills add https://github.com/Effect-TS/skills/tree/155c50c911f9c99c294ef8a4461981c5bbe6453e/skills/effect-v3-to-v4
  1. The command pins only the v3-to-v4 skill at the reviewed commit. The installer was not executed.
  2. Do not point the installer at the repository root. That also installs the stub effect-ts skill, which was not selected.
  3. For manual installation instead, download the complete bundle from https://undominated.ai/resources/skills/effect-ts-effect-v3-to-v4/bundle.zip and extract it into a new directory. It holds SKILL.md unchanged at revision 155c50c9, the upstream licence and an attribution file.
  4. Place the extracted directory in your host's documented skills directory, named effect-v3-to-v4. Keep SKILL.md and the licence together.

Before you start

  • Node.js and npm
  • Git, so the procedure can clone Effect
  • A project type-check command

THE COMPLETE REVIEWED DEFINITION

Read it before you reuse it.

Original source bytes, with attribution.
Review the host-specific setup notes above.

---
name: effect-v3-to-v4
description: Use this skill when migrating a codebase from Effect v3 to Effect v4, upgrading `effect` or any `@effect/*` package across the v3/v4 boundary.
disable-model-invocation: true
---

# Effect v3 to v4 Migration

Drive an Effect v3 → v4 migration from the generated migration reference that ships in the Effect repo. Every rename, removal, and signature change is answered by upstream data — do not guess replacements.

## Workflow

Work through these steps in order; each one is detailed in the section named.

1. **Set up and validate the local checkouts** — two shallow clones; verify any pre-existing `.repos/effect` before trusting it. See **Setup: Local Checkouts**.
2. **Read `MIGRATION.md`** and `ls .repos/effect/migration/` for the background and guide index. See **Reading Order**.
3. **Migrate `package.json`** — remove consolidated packages, align every remaining Effect package on one v4 version. Do this before type-checking, or the first run drowns in unresolved-import noise from packages that no longer exist. See **Repo-Level Changes**.
4. **Run the project's type-check** (e.g. `tsc --noEmit`) to get the initial error inventory.
5. **Iterate until the type-check is clean.** For each error, resolve the API through the lookup discipline — search `migration/v3-to-v4.md` for the symbol, escalate per **Reading Order** — then fix the call site, delegating per-file fixes to sub-agents per **Delegating to Sub-Agents**. Never silence an error instead of resolving it; see **Hard Prohibitions**.
6. **Finish** — type-check clean; run tests and report their outcome honestly (not a gate); write the final summary. See **Done Condition**.

## Setup: Local Checkouts

The migration is driven from two shallow, single-branch clones of the canonical Effect repo:

```sh
git clone --depth 1 --single-branch https://github.com/Effect-TS/effect .repos/effect
git clone --depth 1 --single-branch --branch v3 https://github.com/Effect-TS/effect .repos/effect-v3
```

- `.repos/effect` — v4 (`main`). Contains `MIGRATION.md`, the `migration/` guides, and the v4 source.
- `.repos/effect-v3` — v3 (`v3` branch). Escalation-only reference for old semantics.

Each clone is independently re-runnable and separately deletable. Do not use `git worktree` to share one clone between branches.

### Validate an existing checkout before trusting it

`./.repos/effect` may already exist, cloned from the superseded `Effect-TS/effect-smol` repo by older setup instructions. That checkout is stale and does not contain `migration/v3-to-v4.md`. Verify before using:

```sh
git -C .repos/effect remote get-url origin   # must be the canonical Effect-TS/effect repo
node -p "require('./.repos/effect/packages/effect/package.json').version"   # must be 4.x
```

If the origin points at `effect-smol`, or the version is not `4.x`, delete the directory and re-clone as above.

## Reading Order

1. **Front-load `MIGRATION.md` once** (`.repos/effect/MIGRATION.md`).
2. **`migration/v3-to-v4.md` — the first stop for every API.** The generated reference covers every removed or changed API. Search it (see below); never read it whole.
3. **A per-topic guide** (`.repos/effect/migration/*.md`) when the mapping implies a rewrite rather than a rename — e.g. `Context.Tag` → `Context.Service` is a structural change, not a symbol swap. Reach these on demand from the `MIGRATION.md` index, not front-loaded.
4. **v4 source** (`.repos/effect/packages/*/src/`) to confirm a replacement's real signature before writing code against it.
5. **v3 source** (`.repos/effect-v3`) as escalation only — for when unsure about the old v3 semantics.

## Never Read the Reference Doc Whole

**This is the single most important rule in this skill.** `migration/v3-to-v4.md` is ~17,000 lines / ~350k tokens. Reading it in one pass blows the context window and takes the migration with it.

Always search it and read only matched lines plus surrounding context. The file has four sections — **Import Map**, **No Counterpart Imports**, **Removed Modules**, and **API Reference** (one `` ### `<v3 module path>` `` heading per module). Entries are grep-able one-liners of the form `` - `Old.symbol` -> `New.symbol`: <rationale> ``, and removals are explicit `` -> `none` `` entries with a stated alternative.

Concrete recipes:

```sh
# Look up a specific v3 symbol
rg -n 'AnthropicTokenizer\.layer' .repos/effect/migration/v3-to-v4.md

# Read a whole module's section via its heading
rg -n -A 40 '^### `@effect/platform/FileSystem`' .repos/effect/migration/v3-to-v4.md

# Resolve a v3 import path in the Import Map
rg -n '^@effect/platform/FileSystem ' .repos/effect/migration/v3-to-v4.md

# List every module section for a package
rg -n '^### `@effect/cluster/' .repos/effect/migration/v3-to-v4.md
```

Look up APIs as you encounter them, one search at a time. A miss in the Import Map is not a dead end — check the **Removed Modules** and **No Counterpart Imports** sections before concluding anything.

## Repo-Level Changes

Faithful per-API lookup alone still yields a broken `package.json`. Handle these once, up front:

- **Package consolidation.** `@effect/platform`, `@effect/rpc`, `@effect/cluster`, and others merged into the core `effect` package. Remove them from `package.json` and rewrite their imports per the Import Map. Packages that remain separate (`@effect/platform-*`, `@effect/sql-*`, `@effect/ai-*`, `@effect/opentelemetry`, `@effect/atom-*`, `@effect/vitest`, …) stay as dependencies. The consolidated v3 packages (including `@effect/sql` and `@effect/cli`) still have npm `latest` tags pointing to `0.x`; remove them rather than bumping everything to `latest`.
- **Version alignment.** Target the current stable `latest` 4.x release. All Effect ecosystem packages share one version number in v4, so every remaining `effect` / `@effect/*` dependency must use that same matching version.
- **Module paths and stability.** GA imports use paths such as `effect/http`, `effect/rpc`, and `effect/ai/LanguageModel`. Stability is declared by JSDoc tags, not an import-path segment: `@stability unstable` APIs may receive breaking changes in minor releases, and `@stability experimental` APIs may receive them in patch releases.
  If migrating code that targeted a beta or RC with `effect/unstable/<module>` imports, drop the `unstable` segment (for example, `effect/unstable/http` → `effect/http`). There are no compatibility exports for the old paths; moving a module does not stabilize its API.

## Delegating to Sub-Agents

Per-file migration work is context-hungry; do it in sub-agents so the main session's context survives the whole migration.

- Spawn one sub-agent per file (or per module), giving it the specific v3 symbols to resolve in that file.
- The sub-agent returns the edit and the mappings it used; the main session keeps the error inventory and the running summary.
- Sub-agents inherit the same lookup discipline (**Reading Order**, the `rg` recipes) and **Hard Prohibitions**.
- The reference doc is never read whole in a sub-agent either — a blown sub-agent context still costs the migration that file.

## Hard Prohibitions

- **Never reintroduce a v3-shaped compatibility layer.** Writing a `v3-compat.ts` that re-exports old names makes type errors vanish and permanently freezes the codebase between versions. Migrate call sites to the v4 API.
- **No `any`, no `as` casts** to silence a post-migration type error. Such an error is usually evidence the replacement has a different shape; casting deletes that information. Go back to the reference or the v4 source.
- **No invented APIs.** Every replacement must trace to the reference doc, a topic guide, or the v4 source.

## Done Condition

**The project type-checks against v4.** A v4 migration is fundamentally a type-level exercise; unresolved imports and changed signatures surface there and nowhere else. Run the project's type-check (e.g. `tsc --noEmit`) until clean.

Running the test suite is recommended, and its outcome must be reported honestly — but it is **not** a gate. A repo mid-migration often has tests that cannot run for unrelated reasons; do not weaken tests to make them pass.

The final summary must state: the type-check result, the test result (or why tests were not run), every constructed replacement, and any gaps that were reported rather than bridged.

The download contains SKILL.md. Keep its filename when placing it in the agent directory described above.

By Effectful Technologies. Exact upstream source ↗ · Licence · Attribution

SHA-256 fa788dc91d5fd64320e62e71a21d10c0538228b5662ff9ed0fcddc97d0b2890d

Read the applicable licence
MIT License

Copyright (c) 2023 Effectful Technologies Inc

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

04 / FOLLOW THE EVIDENCE

The source trail.

Our notes are separate from the original resource.
Check upstream before adopting a new version.

  1. Skill definition ↗Checked

    https://github.com/Effect-TS/skills/blob/155c50c911f9c99c294ef8a4461981c5bbe6453e/skills/effect-v3-to-v4/SKILL.md

    Supports: summary, whySelected, limitations

  2. MIT licence ↗Checked

    https://github.com/Effect-TS/skills/blob/155c50c911f9c99c294ef8a4461981c5bbe6453e/LICENSE

    Supports: Redistribution terms

  3. https://github.com/vercel-labs/skills/blob/13e4063a1cf913f5606d57d42ab83a86f5001e04/README.md

    Supports: install

  4. https://github.com/vercel-labs/skills/blob/13e4063a1cf913f5606d57d42ab83a86f5001e04/src/git.ts

    Supports: install

  5. https://raw.githubusercontent.com/Effect-TS/skills/155c50c911f9c99c294ef8a4461981c5bbe6453e/skills/effect-v3-to-v4/SKILL.md

    Supports: upstreamDescription, review.notTested, review.reviewedAt

Evidence & Ask