What is the Five-Part Expansion Pattern?

It is a standardized structure consisting of a rule-based opening sentence, a motivation paragraph, a contrast section (comparison table), the signature block, and a realistic example.

What does this skill consider a 'thin' documentation section?

A section is considered thin if it only shows a method signature and a trivial 'toy' example without explaining the motivation, use-cases, or how it compares to alternatives.

Is this skill specific to Scala and ZIO?

While the verification steps and examples are optimized for Scala and the ZIO ecosystem, the principles of enriching documentation with motivation and contrast apply to any programming language.

How does the skill ensure documentation accuracy?

It instructs the agent to read the underlying source code implementation first and then provides specific sbt/mdoc commands to verify that all code examples type-check correctly.

Technical Documentation Enricher

Name: Technical Documentation Enricher
Author: zio

byzio

•

119

•

学习与文档

Transforms thin documentation stubs into comprehensive sections featuring motivation, comparative analysis, and realistic use-cases.

The Technical Documentation Enricher helps developers bridge the gap between 'what' an API does and 'why' a user should care. By analyzing source code and identifying alternative patterns, this skill expands minimal documentation sections into deep technical guides. It follows a structured five-part expansion pattern—including motivational paragraphs, contrast tables, and production-grade examples—ensuring that readers can make informed architectural decisions. Optimized for libraries using mdoc, it also provides verification steps to ensure all generated examples are type-safe and syntactically correct.

主要功能

01Generates realistic, production-grade usage examples for complex scenarios

02119 GitHub stars

03Identifies 'thin' sections that lack context or motivation

04Creates comparative tables to guide users between similar API choices

05Includes mdoc-specific verification workflows for Scala environments

06Analyzes source code to find functional contrasts and alternatives

使用场景

01Clarifying the trade-offs between similar methods in a technical library

02Converting autogenerated API references into high-quality educational guides

03Replacing generic toy examples with realistic middleware or gateway scenarios

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add zio/zio-blocks docs-enrich-section

For use in Claude.ai and ChatGPT