writing-revision

Files (6)

• README.md
• SKILL.md
• openai.yaml · agents/
• hero.png · images/
• technical-writing.md · references/
• writing.md · references/

SKILL.md (first lines)

# Writing Revision

Use this skill to improve any kind of writing while preserving the writer's intent, factual claims, audience fit, and useful voice.

## Workflow

1. Read `references/writing.md`.
2. For technical writing, docs, changelogs, UI copy, onboarding text, help text, or product explanations, extend the base workflow with `references/technical-writing.md`.
3. Identify the writing situation before editing:
   - format
   - audience
   - goal
   - desired tone
   - constraints or facts that must stay fixed
4. Rewrite in passes:
   - purpose and reader fit
   - structure and flow
   - paragraph shape
   - sentence clarity
   - voice, tone, and rhythm
   - final polish
5. Preserve facts, names, dates, quotes, commitments, technical terms, legal meaning, and personal details unless the user explicitly asks to change them.
6. For technical writing, apply the technical extension after the base writing pass: technical precision, executable examples, exact UI labels, identifiers, and product truth take priority over smoothness.

## Revision Rules

- Make the main point easy to find.
- Match the structure to the reader's job and the piece's purpose.
- Keep one dominant idea per paragraph or section.
- Prefer concrete language over vague abstraction.
- Improve rhythm without making the writing sound generic.
- Preserve the writer's voice when revising existing text.
- Cut filler and repeated ideas.
- Avoid em dashes. Use space-padded hyphens (` - `), colons, semicolons, commas, or sentence breaks when they fit better.
- Remove cliches, stock idioms, and familiar figures of speech unless the user explicitly wants that register.
- Add transitions only when they clarify the relationship between ideas.
- Do not make claims stronger than the source supports.
- Do not over-polish personal, emotional, or opinionated writing until it loses its human texture.
- Do not rewrite technical detail into vagueness or change commands, paths, labels, version numbers, routes, or identifiers unless they are wrong.

From hugobowne/show-us-your-agent-skills, MIT.

More from hugobowne/show-us-your-agent-skills