improve-writing

Improve Writing Skill

Enhance technical writing clarity, conciseness, and readability while preserving technical accuracy.

Quick Start

Use this skill when:

• Drafting issue descriptions, documentation, or notes
• User requests writing improvement (/improve-writing)
• AI detects unclear or verbose text

Example:

Original: "The thing is that when users are trying to log in to the system,
they sometimes get errors and it doesn't work properly."

Improved: "Users encounter login errors intermittently. Root cause unknown."

Confidence: RECOMMENDED
Changes: Removed filler words, made specific, added action item

Workflow

1. Analyze Text

   • Identify issues:
     • Clarity: Vague terms ("thing", "sometimes", "properly")
     • Conciseness: Filler words ("the thing is", "trying to")
     • Structure: Long sentences, lack of paragraphs
     • Technical accuracy: Imprecise terminology

2. Apply Improvements

   • Clarity:
     • Replace vague terms with specifics
     • Use active voice over passive
     • Define acronyms on first use
   • Conciseness:
     • Remove filler words and redundancy
     • Shorten long sentences (max 25 words)
     • Use bullet points for lists
   • Structure:
     • Add headers for sections
     • Break into digestible paragraphs (3-4 sentences)
     • Use consistent formatting

3. Preserve Technical Content

   • Keep all technical terms and specifics
   • Maintain code examples verbatim
   • Don't alter user intent or meaning

4. Tag Confidence

   • RECOMMENDED: Clear improvement, no ambiguity
   • DEFAULT: General enhancement, maintains meaning
   • ALTERNATIVE: Multiple valid approaches, style preference

Output Format

{
  "original": "Original text...",
  "improved": "Improved text...",
  "confidence": "RECOMMENDED",
  "changes": [
    {"type": "clarity", "description": "Replaced 'thing' with 'authentication module'"},
    {"type": "conciseness", "description": "Removed filler phrase 'the thing is that'"},
    {"type": "structure", "description": "Split into two sentences for readability"}
  ],
  "readability_score": {
    "original": 45,
    "improved": 68,
    "metric": "Flesch Reading Ease"
  },
  "suggestions": [
    "Consider adding code example for login flow",
    "Specify browser/environment for reproducibility"
  ]
}