Writing Clearly And Concisely

What it does

This skill refines written text to improve clarity and conciseness, eliminating jargon and unnecessary words for a better user experience. It draws heavily on principles from William Strunk Jr.'s The Elements of Style to ensure writing is direct, impactful, and easily understood by humans. The skill also helps identify and remove common "AI patterns" that lead to generic or overly verbose prose.

When to use it

This skill is beneficial in the following situations:

• Writing documentation, README files, and technical explanations
• Crafting commit messages and pull request descriptions
• Improving error messages, UI copy, help text, and code comments
• Creating reports or summaries that require clear communication
• Editing existing content to enhance clarity and reduce wordiness

Key capabilities

• Applies principles from The Elements of Style for clear writing.
• Identifies and removes "puffery" (e.g., pivotal, crucial) and empty phrases.
• Eliminates promotional adjectives and overused AI vocabulary (e.g., groundbreaking, leverage).
• Reduces formatting overuse (excessive bullets, bolding).
• Supports a limited context strategy for processing large documents by focusing on specific sections (~1,000-4,500 tokens at a time).

Example prompts

• "Please rewrite this commit message to be more concise: 'Implemented new feature ensuring reliability and showcasing features.'"
• "Can you edit this paragraph to remove unnecessary words and use active voice?"
• "Review this UI copy for clarity and eliminate any promotional language."

Tips & gotchas

• For best results, especially with longer documents, utilize the "Limited Context Strategy" by sending specific sections of text (around 1,000-4,500 tokens) to the skill.
• The skill primarily focuses on clarity and conciseness; it doesn't handle complex technical accuracy checks.
• Referencing the included files (e.g., 03-elementary-principles-of-composition.md) can provide more detailed explanations of the underlying principles.