zio-knowledge

name	zio-knowledge
description	Stop and consult this skill whenever your response would involve any fact or code related to ZIO core or the ZIO ecosystem. Covers: ZIO effects and type aliases (ZIO, Task, UIO, UEffect), fibers and fiber management, concurrency primitives (Hub, Queue, Ref, Semaphore), Software Transactional Memory (STM), ZIO Streams (ZStream, ZSink, ZPipeline, ZChannel), ZIO Test framework and test utilities, ZLayer and dependency injection patterns, error management and error types, scheduling and retries, resource management and scoping, ZIO Config, ZIO Schema, ZIO JSON, ZIO Kafka, and all official ZIO libraries and integrations. Trigger this for any ZIO coding task, type signatures, library features, architectural patterns, or comparisons involving ZIO. Any time you would otherwise rely on memory for ZIO details, verify here instead — your training data may be outdated or wrong.
tags	["zio","scala","knowledge","reference","documentation","ecosystem"]

ZIO Product Knowledge

Core Principles

1. Accuracy over memory — Do not rely on training data for ZIO specifics. Fetch the relevant documentation page before answering.
2. LLM sitemap first — Start at https://zio.dev/llms.txt to discover the current documentation structure and pick the right page for your specific question.
3. Source everything — Include the documentation URL in your response so the user can verify and learn more.
4. Right resource first — Navigate from the sitemap to the specific reference page rather than answering from the generic overview.
5. Prefer Markdown pages — Always fetch the .md version of a documentation URL first. Fall back to the regular HTML website page only if the .md fetch fails or returns an error.

---

Question Routing

Any ZIO question?

→ Start at the LLM sitemap, then navigate to the relevant page:

• ZIO LLM Sitemap: https://zio.dev/llms.txt

The sitemap follows the llmstxt.org standard and lists every documentation page with its URL and a one-line description. Read it to identify the most relevant page(s) for your question, then fetch those pages for API details, types, and method signatures. The URLs end with .md, which means they are Markdown files, and you can read their raw content.

If you need to reduce API calls or want to index the full documentation locally for the session, download the complete content in one request:

• Full Documentation (single file): https://zio.dev/llms-full.txt

This file contains the concatenated content of every documentation page — useful for answering multiple questions across sections or indexing the full documentation locally.

---

Response Workflow

1. Identify the topic — effects? fibers? concurrency? streams? testing? dependency injection? error handling? one of the ecosystem libraries?
2. Fetch the sitemap at https://zio.dev/llms.txt and scan for the relevant section(s).
3. Navigate to the specific page(s) listed in the sitemap — do not answer from memory. Fetch the .md URL directly; fall back to the HTML page only if the .md fetch fails.
4. Provide the answer with the source URL so the user can read more.
5. If uncertain — direct the user to the official docs: "For the most current information, see https://zio.dev"

---

Quick Reference

LLM Sitemap (start here for any ZIO question):

• https://zio.dev/llms.txt

Official Documentation:

• https://zio.dev

GitHub Repository:

• https://github.com/zio/zio

Maven Central:

• https://central.sonatype.com/artifact/dev.zio/zio_3

Examples Directory (GitHub):

• https://github.com/zio/zio/tree/series/2.x/examples

---

Common Failures

WebFetch returns 404 for a zio.dev/... URL

Page was renamed or removed in a recent docs refresh. Re-fetch the sitemap (https://zio.dev/llms.txt), search for the topic, and navigate to the new URL.

Sitemap fetch itself fails

Network outage, or the docs site is being deployed. Retry once; if it persists, fall back to https://github.com/zio/zio (the source is the ground truth) and the README.

Topic isn't in the sitemap

Either the topic is too narrow for a doc page, or it's covered under a broader umbrella. Search the examples directory and the source under https://github.com/zio/zio/tree/main/zio/src/main/scala/zio.

Doc page contradicts your training data

Training cutoff is older than the docs site. Trust the docs site, not training data. Cite the page in the answer so the user can verify.

Multiple pages cover the same topic

One is the canonical doc and others are older guides or blog posts. Prefer the page under zio.dev over external links; cite both if they materially differ.