Use when the user is upgrading effect-uai across versions, sees compile errors after a version bump, or asks Claude to "update my effect-uai code to the latest". Encodes per-version rename tables and behavior changes so Claude can rewrite call sites mechanically without re-reading the changelog each time.
Use when building AI agents and AI media workflows with effect-uai (Effect-based primitives for agent loops, tools, streaming, structured output, embeddings, speech, and music generation). Covers design philosophy, core primitives, provider wiring, and recipe skills for retry, fallback, tool approval, embeddings, transcription, speech synthesis, voice loops, music generation, SSE/JSONL, and more.
Use when the user wants a long-lived chat agent that pulls user messages from a queue, debounces typing bursts into one batch, and only checks for new input between cleanly-finished turns. Mid-task tool exchanges run uninterrupted; new messages are buffered until the next clean turn boundary.
Use when the user wants the canonical effect-uai agent loop — stream a model turn, run any tools the model asks for, append outputs, continue until the model produces a final answer. The starting shape every other recipe is a variation of.
Use when the user wants cost-aware model routing with effect-uai — start on a fast cheap model and let it escalate hard questions to a stronger model via a tool call. Covers the escalate(reason, question) descriptor, prompt-level escalation policy, onTurnComplete interception, tier_active/escalated events, and the difference from provider-failure fallback.
Use when a tool needs to emit progress, partial results, or sub-agent reasoning to the user UI in real time, while still returning one clean structured value to the model. Common cases — sub-agent text streaming, file download with progress, sandboxed exec output, long-running search.
Use when the user wants a human-in-the-loop verdict before sensitive tool calls run (send_email, delete_user, transfer_funds, etc.). Approvals can arrive synchronously bundled with the next HTTP request, or asynchronously over a long-lived queue / WebSocket. Every gated call ends up with a matching function_call_output in history regardless of verdict.
Use when the user wants text-to-speech with effect-uai from finished text — read aloud, generate audio files, notification readers, podcast snippets, or chunked TTS playback. Covers SpeechSynthesizer.synthesize, SpeechSynthesizer.streamSynthesis, AudioBlob / AudioChunk results, provider voice IDs, and OpenAI / Gemini / ElevenLabs / Inworld layers.