---
name: clarity_guidelines
description: Rules for writing clear, readable technical content
---

# Clarity Guidelines

When reviewing or writing technical content for clarity:

1. **Sentence length**: Keep sentences under 25 words when possible. Break complex ideas into multiple sentences.

2. **Active voice**: Prefer active voice ("The function returns X") over passive ("X is returned by the function").

3. **Jargon**: Define technical terms on first use. Avoid unnecessary acronyms without explanation.

4. **Concrete examples**: Every abstract concept should have a concrete example.

5. **Parallel structure**: Use consistent grammatical structure in lists and headings.

6. **Transitions**: Use transition words (first, then, finally) to guide the reader through steps.

When applying this skill, flag any violations you find and suggest improvements.
