---
name: writing
version: 1
category: docs
---

# Writing Assistance

Draft, edit, and improve written content: reports, emails, documentation, and prose.

## When to use this skill

- User wants to write or improve a document, email, report, or message
- User wants content edited for clarity, tone, or conciseness
- User wants help structuring an argument or explanation
- User mentions "write", "draft", "edit", "improve", "proofread", "tone", "rewrite"

## Principles

Good writing is clear before it is eloquent. Prioritize:
1. **Clarity** — can the reader understand this without effort?
2. **Conciseness** — does every word earn its place?
3. **Structure** — does information flow in the order the reader needs it?
4. **Tone** — does it match the audience and context?

## Procedure

### Before writing, establish context

Ask (or infer from context):
- Who is the audience? (technical expert, executive, general public, client)
- What is the purpose? (inform, persuade, instruct, request)
- What tone? (formal, conversational, urgent, warm)
- What format? (email, report, bullet points, narrative)
- What is the one thing the reader should remember?

### Document structure

**For reports and documents:**
1. Executive summary / TL;DR (what, so what, now what)
2. Context and background
3. Findings or main content
4. Recommendations or next steps
5. Appendix (supporting detail)

**For emails:**
1. Clear subject line stating the purpose
2. Context sentence (why you're writing)
3. The main point or request
4. Supporting detail (minimal)
5. Clear next step or ask

**For technical documentation:**
1. Overview (what this is and who it's for)
2. Prerequisites
3. How to use / steps
4. Examples
5. Reference / API details
6. Troubleshooting

### Editing existing content

Review in this order:
1. **Structure first** — is the overall organization right? Should sections be reordered?
2. **Paragraph level** — does each paragraph have one main idea? Does it start with the main point?
3. **Sentence level** — are sentences too long? Any passive voice that should be active?
4. **Word level** — remove filler words (very, really, quite, just, that). Replace vague words with specific ones.
5. **Final pass** — read aloud. Does it flow naturally?

### Tone adjustment

- **More formal**: replace contractions, use complete sentences, avoid colloquialisms
- **Less formal**: add contractions, shorter sentences, first-person voice, concrete examples
- **More concise**: cut every word that doesn't change the meaning
- **Warmer**: add "you", address the reader directly, acknowledge their situation

### Common rewrites

| Instead of | Use |
|-----------|-----|
| "In order to" | "To" |
| "Due to the fact that" | "Because" |
| "At this point in time" | "Now" |
| "Is able to" | "Can" |
| "It is important to note that" | Delete it |
| Passive: "was done by" | Active: "[person] did" |

## Output format

When delivering a draft: present the full text.
When editing: either show the revised text directly, or show key changes with brief explanations if the changes are significant.

When the user asks for options, provide 2-3 variations (e.g., formal vs. casual version).

## Pitfalls

- Don't start writing before understanding the audience and purpose
- Avoid jargon unless the audience definitely knows it
- Don't pad — length is not quality. Say it in fewer words
- Spell out acronyms on first use
- Active voice is almost always clearer than passive
- Never invent facts or figures — if you need a number, ask the user or flag it as a placeholder

## Verification

After drafting: read the full piece through from the reader's perspective. Does it answer their likely questions? Is the ask or conclusion clear?
