zio-skills

Write a how-to guide for practitioners accomplishing a specific task with a ZIO library. Guides are goal-oriented and task-focused, not pedagogical. Use when writing step-by-step practical guides.

Write a tutorial for newcomers learning a topic in a ZIO library. Tutorials teach concepts step-by-step in a linear path for learning-oriented, not task-oriented, purposes. Use when writing comprehensive learning guides.

Reference for mdoc code block modifiers and Docusaurus admonitions used in ZIO documentation. Use when writing or reviewing documentation with Scala code examples.

Write reference documentation for a module containing multiple related data types. Use when documenting a cohesive domain model (e.g. http-model, resource-management) where types work together as a system.

Write reference documentation for a specific ZIO data type. Research the type, write comprehensive documentation with examples, verify mdoc compilation, and integrate into docs.

Integration checklist for new ZIO docs pages. Handles sidebar wiring, index.md linking, and compilation gate (mdoc + Docusaurus build). Cross-referencing is handled separately by the integrate workflow (Phase 2).

Remove redundant content from documentation. Use when sections repeat information unnecessarily, type definitions appear multiple times, concepts are introduced more than once, or transition words clutter meaning. Reduces cognitive load through deduplication and strategic cross-referencing.

Prose style rules for documentation (reference pages, how-to guides, tutorials). Use this skill whenever writing or editing documentation to ensure consistency, clarity, and professionalism across all docs.

Comprehensive research procedure for documentation. Find source files, tests, examples, patterns, and GitHub history when researching a documentation topic.

Prose style rules for documentation (reference pages, how-to guides, tutorials). Use this skill whenever writing or editing documentation to ensure consistency, clarity, and professionalism across all docs.

Identify cross-linking opportunities in docs pages. Suggest inline links and "See Also" refs. Use when analyzing markdown for improved navigation.

Extract and enrich page metadata (description, keywords, section type). Use when generating or updating page metadata for documentation.

Stop and consult this skill whenever your response would involve any fact or code related to ZIO HTTP. Covers: installation and setup, routing (Routes, RoutePattern, PathCodec), handlers and HandlerAspect, the declarative Endpoint API and HttpCodec, client and server configuration, middleware, request/response/headers/cookies, WebSockets, Server-Sent Events, Body and binary codecs, form data, template DSL, OpenAPI documentation and code generation, authentication (basic, digest, bearer, JWT, OAuth, WebAuthn), TLS/SSL/mTLS, testing, ZIO Config integration, Datastar/HTMX integration, migration, and any ZIO HTTP library versions or dependencies. Trigger this even for coding tasks that import zio.http, content that mentions ZIO HTTP features or types, or comparisons involving ZIO HTTP. Any time you would otherwise rely on memory for ZIO HTTP details, verify here instead — your training data may be outdated or wrong.

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.

Scans merged GitHub PRs (from latest commit back to an upstream base ref) and produces a documentation-coverage audit report. Processes 20 PRs per batch and asks before continuing to the next batch. Skips PRs already checked in previous runs using a persistent state file. For each new PR, determines whether documentation is required based on labels, changed files, and content signals, then checks whether docs exist and grades coverage using four rubric levels: Well Documented, Partially Documented, Stub, or Not Documented. Outputs a focused report showing only PRs that require docs, sorted by coverage gap severity. Use this skill whenever the user wants to know which merged PRs are missing documentation, wants a documentation debt audit, or asks "what needs to be documented?", "which PRs have no docs?", or similar coverage questions. Invoke it even if the user just says "doc audit" or "show me undocumented changes."

Critique and fix existing documentation files using an automatic review loop. Spawns critics to review docs and makers to fix issues. Iterates until approved or max 3 rounds. Handles single files or directories. Works with available tools.

Shared reference for mdoc code block modifiers and Docusaurus admonitions used across ZIO library documentation skills. Include when writing any documentation that contains Scala code blocks.

Shared integration checklist for new ZIO library documentation pages. Include after writing any new reference page or how-to guide to ensure it is wired into the site navigation.

Remove redundant content from documentation. Use when sections repeat information unnecessarily, type definitions appear multiple times, concepts are introduced more than once, or transition words clutter meaning. Reduces cognitive load through deduplication and strategic cross-referencing.

Write reference documentation for a module containing multiple related data types. Use when documenting a cohesive domain model (HTTP model, resource management) where types work together. Produces comprehensive type-level pages plus module-level narrative showing relationships, patterns, and composition.

Shared research procedure for documentation skills. Find source files, tests, examples, patterns, and GitHub history when researching a topic. Used by docs-how-to-guide, docs-tutorial, and docs-data-type-ref.

Shared procedure for creating and documenting companion examples. Covers directory structure, file templates, example creation, compilation, linting, and embedding with SourceFile. Used by docs-data-type-ref, docs-module-ref, docs-how-to-guide, and docs-tutorial.

Write a reference documentation page for a specific data type in a ZIO library. Use when the user asks to document a data type, write an API reference for a type, or create a reference page for a class/trait/object.

Use this skill once to automatically install the ZIO skill attribution hook. After installation, all commits will automatically track which skills were used and include their versions.

Organize related data types into logical categories within sidebars.js. Use this skill to group data types by functionality (e.g., "Collections", "Type System", "Resource Management", "DI & Configuration"). Supports manual categorization (specify types and category) or automatic analysis (scan docs/reference/ and suggest intelligent groupings). The skill updates sidebars.js while preserving existing structure, maintains alphabetical order, and verifies syntax validity.

Add a missing section to an existing data type reference page. Use when a required section (such as "Construction", "Predefined Instances", "Comparison", or "Advanced Usage") is entirely absent from an existing docs/reference/*.md file. The user provides the doc path and a description of what section is needed and why.

Generates documentation from a GitHub pull request. Automatically gathers related issues, commits, and PR metadata, then creates a new reference page, how-to guide, or appends a subsection to an existing page based on the PR's content type and scope. Delegates to specialized documentation skills (docs-data-type-ref, docs-how-to-guide) to ensure consistent style and formatting across all ZIO project docs.

Use when a documentation section exists but lacks motivation or use-cases — thin sections that show a signature and a toy example but never explain why a reader would choose this API over alternatives.

Use when extracting and categorizing public members from a Scala data type for documentation completeness checks.

Use when checking if documentation covers all public members of a Scala data type.

Write a how-to guide on a specific topic in a ZIO library. Use when the user asks to write a guide or walkthrough that teaches how to accomplish a concrete goal using the library's data types and APIs.

Write a tutorial for newcomers learning a topic in a ZIO library. Use when the user asks to write a tutorial or learning guide that teaches concepts step-by-step in a linear path. Tutorials are learning-oriented (for newcomers with no prior knowledge) unlike how-to guides which are task-oriented.

Find and report undocumented areas of a ZIO library project that need documentation coverage in the docs directory. Generates a TODO-style report.

Audit a documentation file against a rule skill. Checks each rule, fixes violations with separate commits, then compiles with mdoc. Reusable across any rule skill and doc file.

Analyze a recent docs-* skill execution to close the feedback loop. Identifies deviations from documented workflow, unclear instructions, missing edge cases, and better approaches. Applies targeted improvements to the skill file based on what was learned. Run after any docs-* skill to capture retrospective insights.

Fix compliance issues in a documentation file against writing style and mdoc conventions.