Agent Skills: Effect v4 (Beta) - Development & Migration

Effect v4 (Beta) - Development & Migration

Overview

Comprehensive guidance for Effect v4 development and migration from v3. This skill provides:

1. v4 Core Patterns - Guide to building new v4 code with Context, layers, generators, schema codecs
2. v3 → v4 Migration - Step-by-step migration guidance with API renames, behavior changes, and before/after examples

Status: Effect v4 is beta software under active development in effect-smol. The core programming model is stable, but effect/unstable/* modules may receive breaking changes in minor releases. For production use, review official v4 beta guidance and stability notes.

All bundled migration guides are sourced from the official effect-smol migration documentation.

Upstream Changes Since February 22, 2026

The upstream beta changed substantially after this skill was last refreshed. Treat older examples that mention ServiceMap or Schema.makeUnsafe as stale. Current guidance should prefer:

• Context.Service / Context.Reference / Context<R> instead of ServiceMap.*
• Schema.make(...) instead of Schema.makeUnsafe(...)
• Schema.makeEffect(...) when constructor-style validation should fail in the error channel instead of throwing

Quick Triage

Building v4 Code

• Core Effect types and combinators (Result, Option, Chunk, Duration): references/core-usage.md
• Broader data types (DateTime, BigDecimal, HashSet, Redacted): references/data-types-advanced.md
• Equality, Order, Hash, Equivalence semantics: references/behavior-traits.md
• Expected errors vs defects, catch* combinators: references/error-management.md
• Sandboxing, Cause inspection, catchCause: references/error-tooling.md
• Exit and Cause structure, result inspection: references/exit-cause.md
• Services and dependency injection (Context, layers): references/dependency-management.md
• Layer construction, memoization, { local: true }: references/layer-patterns.md
• Resource lifecycles, Scope, acquireRelease: references/resource-management.md
• Running effects, Runtime removal, run boundaries: references/runtime-execution.md
• Fibers, forkChild, forkDetach, fork options: references/concurrency.md
• References (replaces FiberRef), Context.Reference: references/concurrency-advanced.md
• Schedules, repetition, spaced/fixed/exponential: references/scheduling.md
• Retries, backoff, schedule composition: references/scheduling-retry.md
• Streams, queues, PubSub, STM: references/streams-queues-stm.md
• HTTP clients and external APIs: references/http-client.md
• HTTP servers and API definitions: references/http-server.md
• Request batching and data loaders: references/request-resolver.md
• Caching and memoization: references/caching.md
• Configuration and config providers: references/configuration.md
• Advanced config, redaction: references/configuration-advanced.md
• Logs, metrics, tracing: references/observability.md
• Logger/metrics/tracing setups and exporters: references/observability-examples.md
• Wiring log/metric/trace layers: references/observability-wiring.md
• Sequential workflows and yieldable patterns: references/generators.md
• Schema validation, parsing, encoding (codecs): references/schema.md
• Stream consumption with reducers (Sink): references/sink.md
• Deterministic time in tests (TestClock): references/testing.md
• Broader testing services and test layers: references/testing-stack.md
• Command, FileSystem, Path, Terminal, KeyValueStore: references/platform-primitives.md
• LLM workflows, planning, tool use via Effect AI: references/ai.md
• Bundle-size constrained runtimes (Micro): references/micro.md
• Migrating from Promise/async: references/migration-async.md
• Common pitfalls and runtime errors: references/troubleshooting.md
• Docs-to-guide map from llms.txt: references/docs-index.md

Migrating from v3

• Full migration overview, quick-reference table, ordered checklist: references/migration.md
• Runtime and run functions: references/migration/runtime.md
• Error handling and error channel changes: references/migration/error-handling.md
• Cause flattening and new structure: references/migration/cause.md
• Services and environment changes (Context.Tag / Effect.Service → Context.Service): references/migration/services.md
• Fiber references and context locals: references/migration/fiberref.md
• Forking and fiber APIs (fork → forkChild, etc.): references/migration/forking.md
• Fiber keep-alive behavior changes: references/migration/fiber-keep-alive.md
• Scope and resource lifecycle patterns: references/migration/scope.md
• Layer memoization and Layer.fresh: references/migration/layer-memoization.md
• Generator and Effect.gen changes: references/migration/generators.md
• Yieldable protocol (non-Effect yieldables): references/migration/yieldable.md
• Equality and structural comparison: references/migration/equality.md

Workflow

1. Ask which v3 APIs or files are in scope and which failures or regressions to avoid.
2. Open only the relevant migration notes from references/migration/.
3. Produce a mapping of v3 to v4 APIs, including before/after code snippets.
4. Call out behavior changes, edge cases, and test updates needed.
5. Provide a short, ordered migration checklist tailored to the code in question.

Source of Truth

• Start with the bundled references in this skill.
• If the question depends on newer beta behavior, check the official docs and effect-smol changelogs next.
• Only inspect effect-smol source internals when the docs/changelogs are ambiguous, the user is asking about internals, or the behavior appears undocumented.
• Do not clone or read the repo source by default when the bundled references or official docs already answer the question.

Example Requests

• "Migrate this v3 Runtime usage to v4 and explain the new run functions."
• "Update our v3 error handling to v4 and show before/after examples."
• "We use FiberRefs and forking; what needs to change in v4?"
• "Explain the generator/yieldable changes and update this Effect.gen usage."
• "Do we need to change any Scope or Layer memoization behavior in v4?"

References - v4 Core

Comprehensive v4-specific guides (all updated for v4 APIs, no deprecated patterns):

• references/core-usage.md - Core Effect types and combinators (Result, Option, Chunk)
• references/data-types-advanced.md - DateTime, BigDecimal, HashSet, Redacted
• references/behavior-traits.md - Structural equality by default, Equal, Order, Hash
• references/error-management.md - catch* renames, catchReason, catchEager
• references/error-tooling.md - catchCause, sandboxing, Cause inspection
• references/exit-cause.md - Flattened Cause structure, Reason iteration
• references/dependency-management.md - Context, services, layers
• references/layer-patterns.md - Cross-provide memoization, { local: true }
• references/resource-management.md - Scope.provide (was Scope.extend)
• references/runtime-execution.md - Runtime<R> removed, run* at the edge
• references/concurrency.md - forkChild/forkDetach, fork options, keep-alive
• references/concurrency-advanced.md - Context.Reference (was FiberRef)
• references/scheduling.md - Schedules and repetition
• references/scheduling-retry.md - Retries and backoff
• references/streams-queues-stm.md - Streams, queues, PubSub, STM
• references/http-client.md - HTTP clients
• references/http-server.md - HTTP servers
• references/request-resolver.md - Request batching
• references/caching.md - Caching and memoization
• references/configuration.md - Configuration
• references/configuration-advanced.md - Advanced config, redaction
• references/observability.md - Logs, metrics, tracing
• references/observability-examples.md - Concrete logger/metrics/tracing setups
• references/observability-wiring.md - Wiring observability layers
• references/generators.md - Effect.gen and yieldable patterns
• references/schema.md - Schema codecs plus Schema.make / Schema.makeEffect
• references/sink.md - Stream consumption with Sink
• references/testing.md - TestClock and deterministic time
• references/testing-stack.md - Test layer composition
• references/platform-primitives.md - Command, FileSystem, Path, Terminal
• references/ai.md - LLM workflows via Effect AI
• references/micro.md - Bundle-size constrained runtimes
• references/migration-async.md - Migrating from Promise/async
• references/troubleshooting.md - Common pitfalls
• references/versioning.md - Version guidance
• references/docs-index.md - Docs-to-guide routing map

References - v3 → v4 Migration

• references/migration.md - Start here: full overview, quick-reference table, ordered checklist
• references/migration/cause.md - Cause flattening and structure
• references/migration/equality.md - Equality and comparison changes
• references/migration/error-handling.md - Error channel and catch* renames
• references/migration/fiber-keep-alive.md - Fiber lifecycle changes
• references/migration/fiberref.md - FiberRef and References changes
• references/migration/forking.md - Fork, forkChild, forkDetach changes
• references/migration/generators.md - Effect.gen pattern updates
• references/migration/layer-memoization.md - Layer.fresh and memoization
• references/migration/runtime.md - Runtime and run* functions
• references/migration/scope.md - Scope and resource lifecycle
• references/migration/services.md - Current Context.Service API and older beta ServiceMap rename fallout
• references/migration/yieldable.md - Yieldable protocol changes