writing

WallysonGalvao's avatarfrom WallysonGalvao

Clear writing standards based on Zinsser's principles. Use for documentation, commit messages, PR descriptions, and technical communication.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026
[Technical Writing]

When & Why to Use This Skill

This Claude skill implements professional writing standards based on William Zinsser's 'On Writing Well' to enhance technical communication. It streamlines the creation of documentation, commit messages, and PR descriptions by enforcing clarity, brevity, and simplicity, ensuring that every word serves a specific purpose and complex ideas are communicated effectively.

Use Cases

  • Standardizing Git commit messages using an action-oriented <verb> <what> pattern to improve repository maintainability.
  • Drafting structured Pull Request descriptions that clearly outline the summary, motivation, and testing steps for code changes.
  • Refining technical documentation and README files to eliminate jargon, use active voice, and improve overall readability for developers.
  • Creating user-friendly error messages that provide clear context and actionable instructions for troubleshooting.
namewriting
descriptionClear writing standards based on Zinsser's principles. Use for documentation, commit messages, PR descriptions, and technical communication.

Writing Standards

Based on William Zinsser's "On Writing Well".

Core Principles

Clarity

  • One idea per sentence
  • Short sentences (<25 words)
  • Active voice ("We fixed" not "was fixed")

Brevity

  • Every word must earn its place
  • Cut redundant words
  • Delete clutter

Simplicity

  • Simple words over complex
  • Concrete over abstract
  • Specific over vague

Patterns

Commit Messages

<verb> <what>
  • Add user authentication
  • Fix payment validation
  • Refactor database queries

Never: "Fixed stuff", "Updates", "Claude Code"

PR Descriptions

## Summary
[One sentence: what changed]

## Why
[One paragraph: motivation]

## Testing
[How to verify]

Error Messages

<What happened>. <What to do>.
  • User not found. Check the email.
  • Payment failed. Retry or contact support.

Documentation

  1. What it does (one sentence)
  2. Why it exists (one paragraph)
  3. How to use it (clear steps)
  4. Examples (if needed)

Avoid

  • Passive voice
  • Redundant words ("in order to" → "to")
  • Jargon without explanation
  • Hedging ("might", "possibly")
  • Long paragraphs (>5 sentences)

Test Your Writing

  • Can you cut 30%?
  • Is every word necessary?
  • Would you say this to a friend?
  • Can someone skim and understand?