clear-writing

What This Skill Does

The clear-writing skill acts as an editor-in-residence for your technical communications. It enforces the rigorous principles of William Strunk Jr.'s The Elements of Style while applying modern technical documentation standards like Divio's four-part structure (tutorials, how-to guides, reference, and explanation). The skill functions by stripping away the "AI voice"—characterized by repetitive, overly polite, and wordy prose—and replacing it with clear, concrete, and authoritative language.

By leveraging this skill, you ensure your documentation remains accessible to humans, not just algorithms. It actively identifies and repairs passive voice, redundant phrasing, and abstract jargon, ensuring your READMEs, commit messages, and API guides are as efficient as the code they describe.

Installation

To integrate this skill into your OpenClaw environment, run the following command in your terminal:

clawhub install openclaw/skills/skills/wpank/clear-writing

Once installed, ensure your local documentation directory has access to the provided reference files to allow for deep-context editing if necessary.

Use Cases

• API Documentation: Transforming sprawling endpoint descriptions into concise, action-oriented references.
• Commit Messages: Enforcing a standardized, imperative tone that explains the 'why' rather than just the 'what'.
• Error Messages: Converting cryptic system failures into user-friendly diagnostic text with clear next steps.
• Technical Reports: Refining complex architectural summaries to prioritize impact and readability for stakeholders.
• Tutorial Creation: Structuring onboarding material so users can achieve "quick wins" while learning core concepts.

Example Prompts

1. "Rewrite this API endpoint description to be more concise. Remove the fluff and emphasize the required request parameters: [Paste Text]"
2. "Review my commit message for clarity and ensure it follows the imperative mood: 'I went ahead and fixed the bug in the authentication module which was causing issues with the session token.'"
3. "Edit this README introduction to strictly adhere to Strunk's rules on active voice and concrete language. Make the value proposition punchy and professional: [Paste README]"

Tips & Limitations

• Prioritize the 'Elementary Principles of Composition': When in doubt, reference 03-elementary-principles-of-composition.md. It covers 90% of common writing failures.
• Avoid 'AI-speak': Do not prompt the model to be 'friendly' or 'helpful.' Instead, instruct it to be 'direct' or 'technical.' Over-praising or using robotic filler words ('I hope this helps,' 'Furthermore,' 'It is important to note') should be explicitly prohibited in your custom instructions.
• Context Efficiency: If your documentation is long, split it into chunks. Use the Limited Context Strategy to send only the relevant section along with the style guide to prevent the model from hallucinating or losing focus.