Ultimate Writing Clearly And

A practical skill for clear and concise writing — covering the principles of readable prose, eliminating unnecessary words, avoiding AI-sounding patterns, writing with active voice, and producing documentation, README files, and technical content that humans actually want to read.

When to Use This Skill

Choose Ultimate Writing Clearly And when you need to:

• Write documentation, READMEs, or technical explanations
• Edit prose for clarity, conciseness, and readability
• Eliminate AI-sounding patterns from generated text
• Write commit messages, PR descriptions, and changelogs
• Create user-facing copy that sounds natural and direct

Consider alternatives when:

• You need marketing copywriting (use a marketing copy skill)
• You need creative fiction writing (use a creative writing skill)
• You need academic or research paper formatting (use an academic skill)

Quick Start

Copy
# Ask for a writing review
claude "Review this paragraph for clarity and conciseness: 'In order to utilize the functionality of the system, users should navigate to the settings page where they can configure the various parameters that are available for customization in a manner that aligns with their specific needs and requirements.'"

Copy
# Before (42 words)
"In order to utilize the functionality of the system,
users should navigate to the settings page where they
can configure the various parameters that are available
for customization in a manner that aligns with their
specific needs and requirements."

# After (12 words)
"Go to Settings to customize the system to your needs."

## What Changed
- "In order to utilize the functionality" → "Go to"
- "navigate to the settings page" → "Settings"
- "configure the various parameters that are available
  for customization" → "customize"
- "in a manner that aligns with their specific needs
  and requirements" → "to your needs"

Core Concepts

Writing Principles

Principle	Rule	Example
Use active voice	Subject → verb → object	"The script deletes old logs"
Cut filler words	Remove words that add no meaning	"basically", "in order to"
Be specific	Replace vague words with precise ones	"fast" → "under 50ms"
One idea per sentence	Don't stack multiple thoughts	Split compound sentences
Show, don't tell	Give examples instead of abstractions	Code sample > description

Words to Eliminate

Copy
## Common Filler Phrases → Replacements

| Filler                          | Replacement       |
|--------------------------------|-------------------|
| In order to                    | To                |
| Due to the fact that           | Because           |
| At this point in time          | Now               |
| In the event that              | If                |
| It is important to note that   | (delete entirely) |
| Utilize                        | Use               |
| Facilitate                     | Help / Enable     |
| Leverage                       | Use               |
| Functionality                  | Features          |
| Methodology                    | Method            |
| Prior to                       | Before            |
| Subsequent to                  | After             |
| A number of                    | Several / Many    |
| In terms of                    | (rephrase)        |

## AI-Sounding Patterns to Avoid
- "It's worth noting that..." (just say it)
- "Let's dive into..." (just start)
- "In today's landscape..." (be specific)
- "Robust and scalable solution" (what does it do?)
- "Seamless integration" (how does it integrate?)
- "This powerful tool..." (let the reader judge)
- Starting with "Certainly!" or "Absolutely!"

Active vs. Passive Voice

Copy
## Passive → Active Transformations

### Technical Writing
❌ "The configuration file is read by the application"
✅ "The application reads the configuration file"

❌ "Errors are logged to the console"
✅ "The logger writes errors to the console"

❌ "The request is validated before processing"
✅ "The middleware validates the request before processing"

### Documentation
❌ "It can be seen that the function returns null"
✅ "The function returns null"

❌ "This feature was designed to handle edge cases"
✅ "This feature handles edge cases"

### When Passive Voice Is OK
- "The server was compromised" (actor unknown/irrelevant)
- "The file is stored in /tmp" (focus on the object)
- Error messages: "Request denied" (focus on outcome)

Sentence Structure

Copy
## Writing Readable Sentences

### Length
- Target: 15-20 words per sentence average
- Maximum: 30 words (split if longer)
- Vary length for rhythm (short. Then medium.)

### Structure
- Lead with the subject (what the sentence is about)
- Put important information first
- End with new or emphasized information

### Before / After
❌ "When considering the implementation of a caching
   layer, which could potentially improve performance
   by reducing database load, it would be advisable
   to first evaluate whether the current bottleneck
   is actually at the database level." (43 words)

✅ "Before adding a cache, check whether the database
   is actually the bottleneck." (12 words)

Configuration

Parameter	Description	Example
mode	Writing or editing mode	"write" / "edit"
audience	Target reader	"developer" / "user"
tone	Desired tone	"technical" / "casual"
max_sentence	Maximum words per sentence	25
remove_ai_patterns	Eliminate AI-sounding phrases	true
format	Output format	"markdown" / "text"

Best Practices

1. Cut your first draft by 30-50% — Most first drafts are twice as long as they need to be. Read every sentence and ask: "Does this add information the reader needs?" If not, delete it. Shorter is almost always better.

2. Read your writing aloud — Awkward phrasing, run-on sentences, and unnatural tone become obvious when you hear them. If you stumble while reading aloud, the reader will stumble too. Rewrite until it sounds natural.

3. Start sentences with the subject, not with conditionals — "If the user hasn't configured SSL, the server will..." buries the subject. "The server requires SSL configuration" leads with what matters. Reserve conditional openings for genuinely conditional statements.

4. Use concrete nouns and specific verbs — "The system processes the data" is vague. "The API server parses the JSON payload" is specific. Concrete language creates clearer mental models for the reader.

5. Delete every word that doesn't earn its place — "The function basically just returns the input" → "The function returns the input." Words like "basically," "just," "really," "actually," and "simply" rarely add meaning. Remove them and see if anything is lost.

Common Issues

Writing sounds like AI generated it — Avoid superlatives ("cutting-edge," "revolutionary"), hedging ("it's worth noting"), and formulaic transitions ("let's dive into," "in conclusion"). Write like you're explaining something to a colleague — direct, specific, and without performance.

Technical documentation is too verbose — Engineers write 500 words when 100 would suffice because they conflate thoroughness with quality. A README that takes 10 minutes to read gets skimmed. One that takes 2 minutes gets read completely. Front-load the essential information and move details to linked pages.

Tone is inconsistent across sections — When multiple people contribute to a document, the tone shifts between sections. One section is casual, the next is formal. Establish a tone early (first paragraph sets the standard) and edit the entire document for consistency before publishing.