SuperAPI AI Directory

zio-blocks-knowledge

Coding & development

View repository

Updated 10-27 01:28

About this skill

ZIO Blocks Knowledge

Core Principles

  1. Accuracy over memory — Do not rely on training data for ZIO Blocks specifics. Fetch the relevant documentation page before answering. If a page contradicts your training data, trust the docs.
  2. MCP tools first, sitemap fallback — If the zio-blocks MCP server is connected, use mcp tools instead of WebFetch. Otherwise start at https://zioblocks.com/llms.txt to discover the current documentation structure and pick the right page for your specific question. Not connected? See https://zioblocks.com/start.md to add it.
  3. Source everything — Include the documentation URL (or doc path, when using the MCP tools) in your response so the user can verify and learn more.
  4. Right resource first — Navigate to the specific block's reference page rather than answering from the generic overview. Each block is a separate zio-blocks-* artifact, so confirm the artifact name, supported platforms (JVM/Scala.js) and Scala versions (2.13/3.x) on its page or in the catalog at https://zioblocks.com/docs/. Some blocks are JVM-only or Scala 3-only (e.g. SQL, Datastar, HTMX).
  5. Prefer Markdown pages — When falling back to WebFetch, 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.
  6. No effect system assumed — ZIO Blocks has no dependency on ZIO. Do not add ZIO imports or ZIO/ZLayer code to answers unless the user asks or a ZIO-integration module (e.g. zio-blocks-sql-zio) is the topic. For core ZIO questions, use the zio-knowledge skill.

Question Routing

Any ZIO Blocks question?

→ Check whether the zio-blocks MCP server (mcp.zioblocks.com/mcp) is connected:

  • MCP available: Call search_docs with the question first. Each result has a path (verified against the local index) or a source_url (external, fetch directly). Fetch the full page with get_doc_page(path). Use get_doc_index to browse all indexed pages when you need to discover paths rather than search by topic.

  • MCP unavailable: Fall back to the LLM sitemap:

    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.


Response Workflow

  1. Identify the block — schema? scope? endpoint? streams? sql? telemetry? Which zio-blocks-* artifact does it live in?
  2. Route, fetch, and answer — do not answer from memory. Follow Question Routing above (MCP tools first, sitemap fallback, applying Core Principle 5 for the .md-first rule), then cite the source per Core Principle 3.
  3. If uncertain — direct the user to the official docs: "For the most current information, see https://zioblocks.com"

Quick Reference

MCP Server (prefer this when connected): https://mcp.zioblocks.com/mcp

LLM Sitemap (fallback, if MCP is not connected): https://zioblocks.com/llms.txt

Full Text File Documentation (single file): https://zioblocks.com/llms-full.txt — the concatenated content of every documentation page. Use it to index the full docs locally in one request when a session needs multiple questions answered across sections, instead of fetching pages individually.

Official Documentation: https://zioblocks.com

GitHub Repository: https://github.com/zio/zio-blocks

Maven Central: https://central.sonatype.com/artifact/dev.zio/zio-blocks-schema_3 (replace schema with the block's module name)


Common Failures

search_docs returns source_url not path — fetch source_url directly, don't call get_doc_page.

get_doc_page fails for a returned path — retry once verbatim, else fall back to sitemap.

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

WebFetch returns 404 for a zioblocks.com/... page — it was renamed or removed. Re-fetch the sitemap (https://zioblocks.com/llms.txt), search for the topic, and navigate to the new URL.

Topic isn't in the sitemap — either it's too narrow for its own page or covered under a broader one. Search the source under https://github.com/zio/zio-blocks.

Multiple pages cover the same topic — prefer the page under zioblocks.com over external links; cite both if they materially differ.