/effect-ts

name: effect-ts
description: "Comprehensive Effect-TS development guide for TypeScript, focused on Effect v4 (the recommended default) with full v3 (stable) support for existing codebases. Use when building, debugging, reviewing, or generating Effect code: typed errors, fibers, Context/Layers, Scope, Schedule, streams, Schema, observability, HTTP, Config, SQL, CLI, RPC, STM, and Effect AI. Includes exhaustive wrong-vs-correct API tables to prevent hallucinated Effect code. Triggers when code imports from 'effect', '@effect/platform', '@effect/ai', or '@effect/sql', or the user mentions Effect-TS, functional TypeScript, Context, Layer, or Schema from Effect."
metadata:
  version: "0.6.2"
  upstream: "effect@4.0.0-beta.92"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/effect-ts
    emoji: "🌀"
    envVars:
      - name: OPENAI_API_KEY
        required: false
        description: OpenAI API key for Effect AI examples using the OpenAI provider.

Effect-TS

Effect is a TypeScript library for building production-grade software with typed errors, structured concurrency, dependency injection, and built-in observability.

Version Detection

Before writing Effect code, detect which version the user is on:

# Check installed version
cat package.json | grep '"effect"'

• **v4.x** (recommended, the direction Effect is heading): `Context.Service`, `Effect.catch`, `Effect.forkChild`, `Schema.TaggedErrorClass`
• **v3.x** (stable, still common in production): `Context.Tag`, `Effect.catchAll`, `Effect.fork`, `Data.TaggedError`

> Note: v4 beta briefly used a `ServiceMap` module, renamed back to `Context` on 2026-04-07 (PR #1961). If you see `ServiceMap.*` in any doc or older beta code, it is the current `Context.*`. Both v3 and v4 import `Context` from `"effect"`; the exports inside differ (`Context.Service` in v4 vs `Context.Tag` in v3).

**Prefer v4 for new projects** - it's where Effect is going. In an existing codebase, match the installed version: don't rewrite v3 code in v4 syntax unless asked. If the version is genuinely unclear, default to v4 and say so. v4 is still in beta, so pin an exact version (`4.0.0-beta.x`) and expect occasional API churn.

Primary Documentation Sources

**v4 (primary):**

• https://github.com/Effect-TS/effect-smol (v4 source + migration guides)
• https://github.com/Effect-TS/effect-smol/blob/main/LLMS.md (v4 LLM guide)

**v3 (for existing codebases):**

• https://effect.website/docs (v3 stable docs)
• https://effect.website/llms.txt (LLM topic index)
• https://effect.website/llms-full.txt (full docs for large context)

**Both versions:**

• https://tim-smart.github.io/effect-io-ai/ (concise API list)

AI Guardrails: Critical Corrections

LLM outputs frequently contain incorrect Effect APIs. Verify every API against the reference docs before using it.

**Common hallucinations (both versions):**

| Wrong (AI often generates) | Correct | |----------------------------------------------|---------------------------------------------------------------| | `Effect.cachedWithTTL(...)` | `Cache.make({ capacity, timeToLive, lookup })` | | `Effect.cachedInvalidateWithTTL(...)` | `cache.invalidate(key)` / `cache.invalidateAll()` | | `Effect.mapError(effect, fn)` | `Effect.mapError(fn)` in pipe, or use `Effect.catchTag` | | `import { Schema } from "@effect/schema"` | `import { Schema } from "effect"` (v3.10+ and all v4) | | `import { JSONSchema } from "@effect/schema"`| `import { JSONSchema } from "effect"` (v3.10+) | | JSON Schema Draft 2020-12 | Effect Schema generates **Draft-07** | | "thread-local storage" | "fiber-local storage" via `FiberRef` (v3) / `Context.Reference` (v4) | | fibers are "cancelled" | fibers are "interrupted" | | all queues have back-pressure | only **bounded** queues; sliding/dropping do not | | `new MyError("message")` | `new MyError({ message: "..." })` (Schema errors take objects) |

**v3-specific hallucinations:**

| Wrong | Correct (v3) | |------------------------------------|-----------------------------------------------------| | `Effect.Service` (function call) | `class Foo extends Effect.Service<Foo>()("id", {})` | | `Effect.match(effect, { ... })` | `Effect.match(effect, { onSuccess, onFailure })` | | `Effect.provide(layer1, layer2)` | `Effect.provide(Layer.merge(layer1, layer2))` |

**v4-specific hallucinations (AI may mix v3/v4):**

| Wrong (v3 API used in v4 code) | Correct (v4) | |-----------------------------------|------------------------------------------------------| | `Context.Tag("X")` (v3 shape) | `Context.Service<X>(id)` or class syntax | | `ServiceMap.Service` / `ServiceMap.Reference` | Renamed back to `Context.Service` / `Context.Reference` on 2026-04-07 | | `Effect.catchAll(fn)` | `Effect.catch(fn)` | | `Effect.fork(effect)` | `Effect.forkChild(effect)` | | `Effect.forkDaemon(effect)` | `Effect.forkDetach(effect)` | | `Data.TaggedError` | `Schema.TaggedErrorClass` | | `FiberRef.get(ref)` | `yield* References.X` (a `Context.Reference`) | | `yield* ref` (Ref as Effect) | `yield* Ref.get(ref)` (Ref is no longer an Effect) | | `yield* fiber` (Fiber as Effect) | `yield* Fiber.join(fiber)` (Fiber is no longer Effect) | | `Logger.Default` / `Logger.Live` | `Logger.layer` (v4 naming convention) | | `Schema.Tagged