effect-ts

What this skill does

# Effect-TS

## Overview

Provide workflows, patterns, and best practices for building Effect-based TypeScript programs, with focused references for errors, dependencies, resources, runtime execution, generators, schema, testing, platform modules, sink/stream processing, and Effect AI.

Primary docs and API sources:
- https://effect.website/llms.txt (LLM-oriented topic index)
- https://effect.website/docs
- https://effect.website/docs/platform
- https://effect.website/docs/ai/introduction
- https://effect.website/docs/additional-resources/api-reference
- https://tim-smart.github.io/effect-io-ai/ (concise API list)

For internal lookups, the effect-docs MCP can be used to search and fetch API references: https://github.com/tim-smart/effect-mcp.

## Progressive Disclosure

1. Start with `references/docs-index.md` for topic routing.
2. Read one primary guide for the task.
3. Read one adjacent guide only if needed (for cross-cutting concerns like testing, runtime, or observability).
4. Avoid loading unrelated references.

## Quick Triage

- If it needs core Effect data types or combinators, open `references/core-usage.md`.
- If it needs broader data-type choices (DateTime, BigDecimal, HashSet, Redacted), open `references/data-types-advanced.md`.
- If it needs equality/order/hash semantics, open `references/behavior-traits.md`.
- If the task is about error modeling or typed failures, open `references/error-management.md`.
- If it needs error tooling (sandboxing, Cause, error-channel transforms), open `references/error-tooling.md`.
- If it involves services/dependencies, open `references/dependency-management.md`.
- If it involves layer construction or test wiring, open `references/layer-patterns.md`.
- If it involves resource lifecycles, open `references/resource-management.md`.
- If it involves running effects or runtime choice, open `references/runtime-execution.md`.
- If it involves fibers or concurrency primitives, open `references/concurrency.md`.
- If it involves interruption, supervision, or fiber refs, open `references/concurrency-advanced.md`.
- If it involves schedules or repetition, open `references/scheduling.md`.
- If it involves retries/backoff or schedule composition, open `references/scheduling-retry.md`.
- If it involves streams, queues, pubsub, or STM, open `references/streams-queues-stm.md`.
- If it involves HTTP clients or external APIs, open `references/http-client.md`.
- If it involves HTTP servers or API definitions, open `references/http-server.md`.
- If it involves request batching or data loaders, open `references/request-resolver.md`.
- If it involves caching or memoization, open `references/caching.md`.
- If it involves configuration or config providers, open `references/configuration.md`.
- If it involves advanced config or redaction, open `references/configuration-advanced.md`.
- If it involves logs, metrics, or tracing, open `references/observability.md`.
- If it needs concrete logger/metrics/tracing setups or exporters, open `references/observability-examples.md`.
- If it needs wiring of log/metric/trace layers, open `references/observability-wiring.md`.
- If it needs sequential/branching readability, open `references/generators.md`.
- If it needs runtime validation/decoding, open `references/schema.md`.
- If it involves stream consumption patterns with reducers, open `references/sink.md`.
- If it needs deterministic time in tests, open `references/testing.md`.
- If it needs broader testing services, open `references/testing-stack.md`.
- If it involves command/file/path/terminal/key-value modules, open `references/platform-primitives.md`.
- If it involves LLM workflows, planning, or tool use via Effect AI, open `references/ai.md`.
- If it involves bundle-size constrained runtimes, open `references/micro.md`.
- If it involves migrating from Promise/async, open `references/migration-async.md`.
- If it needs versioning or signature changes, open `references/versioning.md`.
- If it hits common pitfalls or runtime errors, open `references/troubleshooting.md`.
- If it needs result inspection or debugging, open `references/exit-cause.md`.
- If it needs a docs-to-guide map from `llms.txt`, open `references/docs-index.md`.

## Core Workflow

1. Clarify boundaries and IO; keep core logic as `Effect` values.
2. Choose style: use pipelines for simple composition; use `Effect.gen` for sequential logic.
3. Model errors explicitly: type expected errors; treat defects as unexpected failures.
4. Model dependencies with services, tags, and layers; keep interfaces clean of construction concerns.
5. Manage resource lifecycles with `Scope` when opening/closing resources.
6. Provide the environment via layers and run effects only at the program edge.
7. For platform/infra code, keep side effects in dedicated adapters and expose typed services to domain code.
8. For agent tasks, include a concise rationale for error, concurrency, and runtime choices.

## Output Standards

- Show imports and minimal runnable examples.
- Prefer barrel imports (`from "effect"` / `from "@effect/platform"`) over deep module paths.
- When function-style composition is clearer, use `pipe` from `effect`.
- Keep dependency graphs explicit (services, layers, context tags).
- Include error channel types and call out expected vs defect errors.
- Avoid running effects inside libraries; show runtime usage in entrypoints or tests.
- Prefer examples that compile under current Effect major versions.

## Agent Quality Checklist

- State the target shape as `Effect<A, E, R>` when it helps design decisions.
- Explicitly separate expected errors (`E`) from defects.
- Identify where layers are provided and where `run*` is called.
- For concurrent code, state bounded/unbounded behavior and shutdown strategy.
- For boundary decoding, show Schema usage and where failures are handled.
- For tests, note which test services are provided (`TestContext`, `TestClock`, live overrides).
- For docs uncertainty, consult `references/docs-index.md` and source docs before finalizing APIs.

## References

- Start at `references/docs-index.md` to choose relevant guides quickly.
- Use `references/core-usage.md`, `references/error-management.md`, and `references/dependency-management.md` as defaults for most code tasks.
- Use platform/runtime references (`references/platform-primitives.md`, `references/runtime-execution.md`) for boundary and integration work.
- Use testing/diagnostic references (`references/testing.md`, `references/testing-stack.md`, `references/troubleshooting.md`) for verification and debugging.