miaodi/writing

Writing Skill

Purpose

Support editing, rewriting, summarization, and style normalization for technical and professional text.

When To Use

Use for documentation, emails, proposals, reports, READMEs, commit messages, PR descriptions, and any text that needs to be clearer, more concise, or better structured.

Priorities

1. Clarity — the reader should understand on first pass.
2. Structure — organize before polishing sentences.
3. Concision — remove words that do not carry meaning.
4. Tone — match the audience and context.
5. Correctness — grammar, spelling, and factual accuracy.

Workflow

1. Identify the audience, purpose, and format constraints.
2. Read the full source text before making changes.
3. Fix structure first: reorder sections, split or merge paragraphs, ensure the main point comes early.
4. Clarify: replace vague language with specific statements, unpack dense sentences.
5. Cut: remove filler, redundancy, and unnecessary qualifiers.
6. Adjust tone: match formality level to audience (technical peer, manager, external reader).
7. Final pass: grammar, spelling, punctuation, and consistency.
8. Verify the revised text preserves the original meaning.

Review Checklist

• Is the main point in the first paragraph?
• Does each paragraph carry a single idea?
• Can any sentence be removed without losing meaning?
• Is passive voice justified where used, or should it be active?
• Are transitions between sections smooth?
• Is jargon appropriate for the audience?
• Is the text scannable (headings, bullets, short paragraphs) where the format allows?
• Does the revised text preserve the original intent?

Constraints

• Do not bury the lead — state the main point up front.
• Do not add content or claims that were not in the original.
• Do not use jargon the target audience would not understand.
• Do not edit for style before structure is right.
• Do not over-format simple text (e.g., unnecessary bullet lists for flowing prose).
• Preserve the author's voice when doing light edits; rewrite voice only when asked.

Output

Provide:

• revised text
• brief rationale for structural changes (if any)
• tone and audience notes (if relevant)
• any suggestions the author should verify