Our review
This skill transforms a thin documentation section into a comprehensive presentation with motivation, use-cases, and comparison with alternatives.
Strengths
- Clear five-part structure to systematically enrich a section.
- Encourages source code research to understand implementation details.
- Highlights alternatives and helps readers choose the right API.
- Replaces toy examples with realistic, relevant scenarios.
Limitations
- Requires access to the source code for preliminary research.
- Not suitable for very simple methods with no alternatives.
- The pattern is specific to API documentation, not conceptual guides.
Use this skill when a documentation section only shows a signature and a trivial example, without explaining why to use it or when to choose an alternative.
Do not use it for introductory tutorials or high-level overviews where such depth is unnecessary.
Security analysis
SafeThe skill instructs only on reading source code and writing documentation improvements. It includes a single command `sbt docs/mdoc` for verifying documentation compilation, which is a standard build tool command and poses no security risk in a development context.
No concerns found
Examples
Enrich the documentation section for the `toSchema` method with motivation and a use-case, following the docs-enrich-section pattern.This section only shows a signature and a toy example. Please expand it with a motivation paragraph, a contrast with alternatives, and a realistic example.I have a thin documentation section that needs motivation and use-cases. Apply the five-part expansion pattern: opening sentence, motivation, contrast, signature, and realistic example.name: docs-enrich-section description: 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.
Enrich a Documentation Section with Motivation and Use-Cases
Overview
A thin section answers what but not why. Readers landing on such a section cannot judge when to use the API or how it fits into the larger picture. This skill turns a thin section into one that answers: what does this return, why does it exist, when is it the right choice, and what does a realistic use look like.
Signals That a Section Needs Enriching
- Shows only a signature + a trivial example (toy type, no realistic scenario)
- No mention of alternatives or when not to use this API
- A reader could not decide between this and the nearest related operation from the section alone
- Opening sentence restates the method name without adding context
Source Research (Do This First)
Before writing a word of prose, read the implementation:
- Read the source — understand what the method actually does, not just its signature
- Find the contrast — locate the nearest alternative (e.g.
rebindvstoSchema) and understand the exact difference in return type, requirements, and guarantees - Find real usage — search the docs and example files for existing uses of this API to anchor your realistic example
- Identify the gap — ask: "In what situation would a reader need this but not the alternative?" That gap is the motivation.
The Five-Part Expansion Pattern
Replace the thin section with these five parts, in order:
1. Opening sentence
State what the method returns and the one-line rule for when to use it. Lead with the return type and the key constraint that distinguishes it from alternatives.
DynamicSchema#toSchemareturns aSchema[DynamicValue]— it stays fully in the dynamic world and requires no bindings. Use it when you have received aDynamicSchemaover the wire and need a codec-compatible schema that enforces structural conformance without binding any Scala types.
2. Motivation paragraph
Explain the gap the method fills. Name the scenario where the alternative fails or is impractical. Name the concrete contexts (middleware, gateways, converters, validators) where this method is the right tool.
3. Contrast sentence or table
State explicitly: "Use X when … Use Y instead when …". One sentence is enough if the distinction is clear; a two-row table if the dimensions are multiple.
| Situation | Right choice |
|---|---|
| No Scala types available; need structural validation only | toSchema |
| Have a BindingResolver; need a fully operational Schema[A] | rebind[A] |
4. Signature block
Keep the existing signature block unchanged. Precede it with a bridging sentence ending in :.
5. Realistic example
Replace any toy example (single-field type, no context) with a scenario that could exist in a real application. The scenario should exercise the method's distinguishing behavior — the part that makes it different from the alternative.
Checklist for the example:
- [ ] Models a plausible real scenario (gateway, registry, pipeline, validator)
- [ ] Uses
mdoc:compile-only - [ ] Imports everything it needs
- [ ] No hardcoded output comments (
// None,// "hello", etc.) - [ ] Preceded by a prose sentence ending in
:
Common Mistakes
| Mistake | Fix |
|---|---|
| Motivation paragraph is abstract ("useful in many cases") | Name one concrete scenario. Abstract motivation helps nobody. |
| Contrast buried at the end | Put it before the signature block, after motivation |
| Example uses the same toy type as before | Create a new type that reflects the motivated use-case |
| Prose sentence before code does not end with : | Every sentence immediately before a code fence must end with : |
| Added output comments to show what expressions return | Delete them — mdoc evaluates and renders output automatically |
Verification
After enriching the section, run the mdoc compilation check to ensure all code examples are syntactically correct and type-check:
sbt docs/mdoc
Success criterion: The output contains zero [error] lines. Warnings are acceptable.
If mdoc reports errors: Fix them immediately before marking the enrichment as complete. Do not commit or claim the work is done until all errors are resolved.
API Documentation Generator
Documentation
Automatically generates OpenAPI/Swagger API documentation.
Technical Writer
Documentation
Writes clear technical documentation following top style guides.
Documentation Maintenance
Documentation
This skill provides a structured workflow for updating project documentation including CLAUDE.md, README, and CHANGELOG. It walks through phases like inventorying existing docs, analyzing git history for needed changes, optimizing for AI readability, and ensuring cross-document consistency. Use it when synchronizing documentation with code changes or improving documentation effectiveness for AI coding agents.