# Cats Effect Io

> Helps agents write and review Scala Cats Effect IO code. Use for suspending side effects and non-determinism in IO or F[_], choosing Sync/Async/Temporal/Concurrent/Clock/Random, handling blocking I/O, testing with TestControl, and composing resources, fibers, races, and structured concurrency safely.

- Skill: `alexandru/cats-effect-io` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add alexandru/cats-effect-io`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexandru/cats-effect-io/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: alexandru (https://skillmd.com/u/alexandru)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alexandru/cats-effect-io

---


# Cats Effect IO (Scala)

## Quick start

- Treat every side effect and source of non-determinism as an effect value: return `IO[A]`, `SyncIO[A]`, or `F[A]` with the smallest needed Cats Effect capability.
- Suspend each side-effectful call, not a precomputed result. `Instant.now()`, random/UUID generation, environment reads, and mutable allocation such as `new Array[...]` belong inside `IO(...)`, `Sync[F].delay`, `Clock`, `Random`, or an effectful factory.
- Initialize shared mutable state through `IO`/`F`/`Resource` factories and pass the resulting reference or service around. Do not hide effects in constructors, top-level vals, or default arguments.
- Wrap Java blocking use-phase calls with `IO.interruptible` by default (or `Sync[F].interruptible`); use `blocking` for acquisition, finalizers, and operations that must not be interrupted.
- Use `Resource` to acquire/release resources and `IOApp` for program entry points.
- Prefer structured concurrency (`parTraverse`, `parMapN`, `background`, `Supervisor`) over manual fiber management.
- Do not use `unsafeRun*` (`unsafeRunSync`, `unsafeRunAndForget`, etc.) in app code or tests; for interop with non-Cats-Effect callback APIs, use `Dispatcher`.
- Read `references/cats-effect-io.md` for concepts, recipes, FAQ guidance, and verified samples.
- For deeper `Resource` guidance, use the `cats-effect-resource` skill (install: `npx skills add https://github.com/alexandru/skills --skill cats-effect-resource`).

## Workflow

1. Identify every side effect and non-deterministic value, including time, random values, mutable allocation, and shared-state reads/writes.
2. Choose the effect type: concrete `IO` or polymorphic `F[_]` with the smallest capability (`Clock`, `Random`, `Sync`, `Async`, `Temporal`, `Concurrent`, etc.).
3. Wrap side-effectful code using `IO(...)`, `IO.interruptible`, `IO.blocking`, `IO.async`, or the corresponding typeclass operation.
4. Move initialization of stateful services into `create`/`resource` factories returning `F[A]` or `Resource[F, A]`.
5. Compose effects with `flatMap`/for-comprehensions and collection combinators (`traverse`, `parTraverse`).
6. Use concurrency primitives (`Ref`, `Deferred`, `Queue`, `Semaphore`, `Supervisor`) and structured concurrency to avoid fiber leaks.
7. Keep effect execution at boundaries (`IOApp`, framework runtime); for callback-style interop, bridge with `Dispatcher`.

## Side-effect rules (apply to `IO`, `SyncIO`, and to `F[_]: Sync/Async`)

- All side-effectful functions must return results wrapped in `IO` (or `F[_]` with Cats Effect typeclasses/capabilities).
- Side effects include all non-determinism (call sites are not referentially transparent):
  - Any I/O (files, sockets, console, databases).
  - `Instant.now()`, `System.currentTimeMillis()`, `Random.nextInt()`, `UUID.randomUUID()`.
  - Reads from environment variables, system properties, clocks, random sources, or shared mutable state.
  - Allocating or returning mutable structures when identity or mutation can escape (`Array`, `mutable.Map`, Java collections, `AtomicReference`, caches).
- Private local mutation is acceptable only when the whole mutable block is suspended and no mutable value escapes.

## Blocking I/O rules

- Prefer `IO.interruptible`/`Sync[F].interruptible` for blocking use-phase operations. This gives cancellation a chance to interrupt the underlying thread and is the right default for network/socket-style blocking APIs.
- Do not require a proof that every Java API honors interruption before using `interruptible`; some APIs still ignore interruption, so add a resource-specific cancellation protocol when cancellation responsiveness matters and testing shows interruption is not enough.
- Use `IO.blocking`/`Sync[F].blocking` for acquisition, cleanup, and disposal (`Closeable#close`, `AutoCloseable#close`), where attempted interruption can leave lifecycle state ambiguous.

## Output expectations

- Make side effects explicit in signatures (`IO`/`SyncIO` or `F[_]: Sync/Async`); the guidance here applies equally to concrete `IO` and polymorphic `F[_]`.
- Use the smallest typeclass constraint that supports the needed operations.
- Keep effects as values; do not execute effects in constructors or top-level vals.
- When adding or changing Scala examples, update and compile the bundled `scripts/verify-examples.scala` script.

## Execution and test rules

- `unsafeRun*` is forbidden in production and test code, including `import cats.effect.unsafe.implicits.global`.
- If interop requires running effects from non-Cats-Effect callbacks, use `Dispatcher`.
- Prefer effect-native test styles (return `IO[Assertion]`/`F[Assertion]`) instead of manually running effects.
- Avoid `IO.sleep`/`Thread.sleep` in unit tests unless using virtual time with `TestControl`.

## References

- Load `references/cats-effect-io.md` for documentation summary and patterns.
- For concrete samples, read `references/cats-effect-io.md`; the representative check is `scripts/verify-examples.scala`.
- Use the `cats-effect-resource` skill for Resource-specific workflows and patterns (install: `npx skills add https://github.com/alexandru/skills --skill cats-effect-resource`).