Top 10 Scala Skills for AI Coding Agents

Best for: Cats Effect IO implementation work involving concurrency, blocking, or test control

cats-effect-io is a source-grounded workflow for programs built around Cats Effect IO. It directs an agent to suspend side effects and non-determinism, choose the minimal capability, and keep effect boundaries visible in the resulting Scala code.

Its concurrency guidance covers interruption-safe blocking, Dispatcher interop, structured concurrency, and TestControl. Load it when IO runtime behavior is present in the repository, rather than treating Cats Effect as an assumption attached to every Scala task.

• Suspended side effects and non-determinism
• Minimal capability selection for IO programs
• Interruption-safe blocking and Dispatcher interop
• Structured concurrency and TestControl workflows

Best for: Cats Effect lifecycle changes around files, clients, pools, sockets, or AutoCloseable values

cats-effect-resource is the lifecycle specialist for Cats Effect Resource. Its source-grounded workflow treats acquisition, use, and release as one managed scope, with cancellation-safe finalizers and Resource factories shaping the implementation.

Use this card for resources that cross asynchronous boundaries, including AutoCloseable interop. The workflow keeps use handles inside their valid scope, so an agent can review ownership and cleanup instead of allowing a resource to escape by accident.

• Resource lifecycle and factory construction
• Cancellation-safe finalizer registration
• AutoCloseable interoperability
• No escaped use handles outside scope

Best for: Typed domain error work in Scala code already using Cats MTL or an effect error algebra

cats-mtl-typed-errors is a Cats MTL workflow for typed failures. It uses Raise and Handle with domain ADTs or enums, making error scope handling part of the design rather than leaving failures as incidental strings or broad exceptions.

The source guidance keeps pure Either at parsing and validation borders, while avoiding transformer stacks and nested IO Either combinations in the effectful core. Select it when the codebase has this Cats MTL error style and the task changes its failure contracts.

• Raise and Handle for typed failure scopes
• Domain ADTs and enums for error vocabulary
• Pure Either at parsing and validation borders
• Avoided transformer stacks and nested IO Either

Best for: Scala stream processing in a repository using Akka Streams or Pekko Streams

akka-streams is a source-grounded workflow for Akka Streams and Pekko Streams in Scala. It asks an agent to read the topology, identify materialized values, and preserve backpressure as stages are added or changed.

The card also covers recovery choices and a testkit workflow. Use it when the build and imports show Akka or Pekko Streams. A stream-specific topology review is a concrete repository decision, not a generic Scala default.

• Topology and materialized-value inspection
• Backpressure across stream stages
• Recovery and failure-path decisions
• Akka or Pekko Streams testkit workflow

Best for: ZIO runtime, stream, layer, or STM changes where current API evidence is required

zio-knowledge is a documentation-led workflow for the ZIO runtime, streams, layers, and STM. It directs an agent to retrieve live zio.dev documentation, identify the relevant API signatures, and include citations that explain the chosen current form.

Use the fallback source only when the documentation endpoint is unavailable. This card fits a ZIO repository and a task that needs runtime or concurrency knowledge. It should not be loaded merely because Scala runs on the JVM or because another effect system appears nearby.

• Live zio.dev documentation retrieval
• Current runtime and API signatures
• Streams, layers, and STM guidance
• Citations with a documented source fallback

Best for: ZIO HTTP v3 server or client work with routing, codecs, or OpenAPI requirements

zio-http-knowledge is the ZIO HTTP specialist. Its source-grounded process retrieves live ziohttp documentation, anchors decisions in the current v3 API, and covers typed endpoint and routing work alongside codecs, OpenAPI, servers, and clients.

Select it when the repository actually uses ZIO HTTP and the task crosses an HTTP boundary. When live documentation cannot be retrieved, the workflow permits a source fallback. The card is narrower than zio-knowledge and does not stand in for general Scala web development.

• Live ziohttp documentation retrieval
• Current ZIO HTTP v3 API
• Typed endpoints, routing, and codecs
• OpenAPI, server, and client workflows

Best for: Scala 3 Pekko CQRS and Event Sourcing implementation work in an established persistence model

pekko-cqrs-es-implementation is an implementation workflow for Scala 3 systems using Pekko CQRS and Event Sourcing. It keeps domain logic pure while following Pekko Typed persistence lifecycle rules and using ZIO for coordination where the source workflow calls for it.

The card follows projections and Protobuf event evolution through the implementation boundary. Choose it when those technologies are present and code must be changed. It is an implementation guide for an existing model, rather than a conceptual architecture-tradeoff card.

• Pure Scala 3 domain implementation
• Pekko Typed persistence lifecycle
• ZIO coordination and projections
• Protobuf event evolution checks

Best for: Read-only Scala 2 to 3 modernization, idiom, anti-pattern, recursion, or performance audits

scala-code-optimizer is a read-only and suggestive audit workflow. It examines a full file across findings, covering Scala 2 to 3 modernization, idioms, anti-patterns, recursion safety, and performance classification instead of optimizing one isolated line without context.

Use it when the requested deliverable is an audit or modernization review. Findings should retain their citations and performance classification for later human decisions. This card does not replace the implementation workflow for Cats Effect, ZIO, Pekko, or another named toolchain.

• Full-file findings rather than line-only edits
• Scala 2 to 3 modernization review
• Recursion safety and performance classification
• Read-only suggestions with citations

Best for: Scala 3.8 language changes in a project that has adopted the specified strict conventions

scala3-syntax is a Scala 3 language specialist grounded in a modern Scala 3.8 strict profile. It covers givens and context bounds, enums, fewer braces, explicit nulls, and explicit equality choices for code that has made those conventions part of its build.

Choose this card from compiler settings, source syntax, and project policy. It is deliberately conditional. It does not represent a generic Scala default, and it should not rewrite Scala 2 code or an unconstrained mixed-version repository by assumption.

• Scala 3.8 strict profile decisions
• Givens, context bounds, and enums
• Fewer braces with explicit nulls
• Explicit equality and language migration boundaries

Best for: Scala tests in a project already using Weaver and Cats Effect resource lifecycles

scala-weaver-test is a Weaver testing workflow grounded in suite selection and Expectations composition. It gives an agent a path through test structure, assertion composition, and the lifecycle concerns that arise when Cats Effect Resource is used by a suite.

The source also calls for discipline and property testing, with no committed .only markers or ScalaTest assertions. Load it for a Weaver repository whose test conventions matter; a generic Scala test task needs evidence before this framework-specific card is selected.

• Weaver suite selection and structure
• Expectations composition for assertions
• Cats Effect Resource lifecycle in tests
• Discipline checks without committed .only or ScalaTest