// 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.
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.
| name | docs-writing-style |
| description | 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. |
| allowed-tools | Read, Glob, Grep |
Phase 1 — Planning only, no edits yet Scan the document and identify every prose style violation (Rules 1–25 below). For each violation, create one task:
"Fix style –
<section>:<line>(Rule<N>):<short description>"
Do not touch any source file until the full task list is created and you have listed it for confirmation.
Phase 2 — Execution
Apply all fixes. Mark each task completed as you finish it.
Phase 3 — Mechanical validation
After all tasks are completed, run:
bash ${CLAUDE_PLUGIN_ROOT}/skills/docs-writing-style/check-docs-style.sh <file.md>
Verify exit code is 0. If not, re-open the relevant tasks and fix.
Before validating manually, run the mechanical style checks to catch common violations of the most critical rules:
bash ${CLAUDE_PLUGIN_ROOT}/skills/docs-writing-style/check-docs-style.sh <file.md>
This checks Rules 2, 3, 4, 7, 8, 10, 11, 12, 13, 15, 16, 18, 22, 23, and 25 for mechanical violations. Run with --help for the full rule list and usage examples.
Exit codes:
| Code | Meaning |
|---|---|
0 | No violations — all checked rules pass. |
1 | One or more violations found. Details printed to stdout. |
2 | Invocation error (missing/extra arguments, file not found). |
Rule 8 detects unqualified methods using heuristics (camelCase in backticks, confident if qualified elsewhere). Update SAFE_NAMES in check-docs-style.sh to avoid false positives.
.md
extension. Never use a bare directory name: ✅ [Endpoint](./reference/endpoint/index.md),
❌ [Endpoint](./reference/endpoint).Always qualify method/constructor names:
Bad vs. Good:
map to transform elements" → ✅ "Call Chunk#map to transform elements"apply to construct a binding" → ✅ "Use BindingResolver.apply to construct a binding".query to add a parameter" → ✅ "Use Endpoint#query to add a parameter"Dot-prefixed references (`.method` or `.method(args)`) are always a violation — they imply a receiver without naming it.
Type name alone rule: When referring to a type (not a method), use only its name in backticks with no qualifier: "As derives automatically", "List is a sequence type", "convert to Option".
#) that duplicates the frontmatter title. The frontmatter title is sufficient:Bad vs. Good:
title: "As Type", then document starts with # As Type## Overview or ## Use Cases## for major sections, ### for subsections, and #### for subsubsections. All three levels are fully supported and encouraged.## header and its first ### subheader. Explain why this section exists and what problem it solves. This can be a single sentence or a short paragraph.Bad vs. Good:
## Operations → ### Map (no intro between them)## Operations → To transform values, use these operations. → ### MapBad vs. Good:
## Overview → ### Definition (only one subsection)## Overview (put the definition content directly here)When to use ####: Use #### to organize multiple related topics under a single ###. Example:
### Operations
#### Transformations
#### Filtering
#### Zipping
#### Scanning
Every code block must be preceded by a prose sentence ending with :: Never follow a heading directly with a code block. Always write an intro sentence that ends with :.
Bad vs. Good:
#### Chunk#map → (code block immediately)#### Chunk#map → To transform each element: → (code block)
Between consecutive code blocks, add bridging prose that explains what the next block demonstrates:Next, create the result: (code block)val over var: Use immutable patterns everywhere if possible.Bad vs. Good:
def map[B](f: A => B): ZIO[R, E, B] = ???trait ZIO[-R, +E, +A] { def map[B](f: A => B): ZIO[R, E, B] = ??? }:). The introduction must be contextualized — relate it to what the code demonstrates or why it matters in context (avoid generic phrases like "here's an example" or "we can see this in action").Bad vs. Good:
Bad (minimal spacing):
| Name | Value |
| - | - |
Good (padded for alignment):
| Name | Value |
| ----- | --------- |
import x._ for wildcard imports, never import x.*.using vs implicit, wildcard imports). Scala 2 is always the default tab.Bad vs. Good:
libraryDependencies += "dev.zio" %% "zio-blocks" % "1.0.0"libraryDependencies += "dev.zio" %% "zio-blocks" % "<version>"libraryDependencies += "dev.zio" %% "zio-blocks" % "@VERSION@"