Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions skills/write-prose/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
name: write-prose
description: Writes and revises clear, engaging reader-facing prose in UK English with an adaptable professional, conversational voice. Use for articles, reports, documents, websites, social posts, and substantial prose within other human-facing outputs.
metadata:
type: teaching
disable-model-invocation: false
---

# Write Prose

Teaches a caller to produce natural, reader-fit prose without weakening meaning, evidence or the caller's authority.

## Process

### 1. Fix the communication job

Use the caller's subject, facts, purpose, audience, medium, genre, constraints and required structure. Preserve exact quotations, proper names, technical terms and mandated wording. Use UK English for all other prose.

Load [Preferred Voice](references/PREFERRED-VOICE.md) and use it as the baseline. Adapt its energy and register to the audience, medium and genre. Follow a different voice only when the caller explicitly requests it; retain UK English.

Let the caller own the requested artefact and its factual, structural and procedural rules; apply this skill only to the prose.

### 2. Lead with substance

Make the point, stakes or useful question clear early. Prefer concrete nouns, visible actions, exact details and strong accurate verbs. Explain necessary specialist language in place.

Make reasoning inspectable. Connect a claim to the most useful explanation, example, evidence, comparison, trade-off or consequence. Put evidence near the claim it supports. State uncertainty, limitations and competing considerations plainly, then explain their practical effect.

Never invent experience, personality, quotations, evidence, agreement or certainty to create a voice.

### 3. Shape the reading experience

Give each paragraph or section a discernible job and order information so each part earns the next. Vary sentence shape, length, pace and punctuation when meaning or emphasis changes. Use active voice when agency matters and passive voice when the receiver properly leads.

For prose that needs explanation, emphasis, engagement or information design, load [Writing Techniques](references/WRITING-TECHNIQUES.md). Select only techniques that perform a real job in this piece. Do not satisfy a style quota.

### 4. Revise for natural prose

For multi-paragraph prose, load [Natural Prose Review](references/NATURAL-PROSE-REVIEW.md). Review the whole piece before polishing sentences:

1. Preserve the intended message, factual boundaries and useful structure.
2. Remove repetition, throat-clearing, empty intensifiers and implications already clear to the reader.
3. Replace vague or inflated wording with the most exact familiar language.
4. Break mechanical symmetry and monotonous cadence only where the reading experience needs it.
5. Read for rhythm, then correct grammar, punctuation and UK usage.

End by closing the central loop with the conclusion, implication, recommendation or next action the piece has earned. Stop when another change would only make the prose different rather than clearer, more engaging or more faithful to the brief.
5 changes: 5 additions & 0 deletions skills/write-prose/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
interface:
display_name: 'Write Prose'
short_description: 'Write engaging reader-facing UK prose'
policy:
allow_implicit_invocation: true
20 changes: 20 additions & 0 deletions skills/write-prose/references/NATURAL-PROSE-REVIEW.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Natural Prose Review

Inspect the piece for:

- a generic opening that delays the actual subject;
- vague claims, missing examples or detail that cannot be inspected;
- repeated words, claims, sentence openings, transitions or conclusions;
- clustered or habitual em dashes that flatten their distinctive pause;
- paragraphs with conspicuously uniform length or function;
- repeated balanced clauses or triads;
- inflated vocabulary, needless intensifiers or a register more complex than the reader needs;
- over-explanation, restated implications and a conclusion that merely summarises the summary;
- headings, lists and transitions applied as a template rather than demanded by the material;
- uniform formality that obscures the writer's grounded point of view;
- invented or unchecked quotations, names, dates, numbers, citations or factual claims; and
- false familiarity, personal experience or collective language not supplied by the caller.

Correct the underlying problem. Add specificity instead of decorative variation. Compress repetition instead of swapping synonyms. Change rhythm where thought and emphasis change. Preserve deliberate parallelism, repetition, technical vocabulary and genre conventions when they serve the piece.

Keep an em dash only when its interruption or aside works better than quieter punctuation. Let contractions, sentence lengths and word strength follow meaning and register.
16 changes: 16 additions & 0 deletions skills/write-prose/references/PREFERRED-VOICE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Preferred Voice

Use a **professional but conversational** voice. Sound like a capable person explaining something useful. Keep the voice direct and grounded rather than institutional.

- State the subject or conclusion early, then explain why it holds.
- Prefer the sequence **claim, explanation, example or consequence** when it fits the material.
- Explain choices through relevant criteria and trade-offs rather than declaring one option universally best.
- Use plain language without removing necessary technical substance. Define unfamiliar terms where the reader meets them.
- Use first person for real choices, actions, experience and uncertainty supplied by the caller. Use ordinary contractions when the genre permits them.
- Keep paragraphs focused and transitions meaningful. Vary connectors rather than repeatedly announcing every example, contrast or conclusion.
- Admit a limitation directly and follow it with what it changes.
- Finish practically. Prefer a conclusion, implication, recommendation or next step to a broad flourish.

Adjust the energy, intimacy and pace to the medium. Technical documentation should be calm and explicit. Reports should be evidence-led. Blog posts may be warmer, brisker and more personal. Social posts may compress the thought and sharpen the opening. Preserve the same clarity and grounded reasoning in each.

Add warmth, humour or informality only when the subject and relationship support it.
33 changes: 33 additions & 0 deletions skills/write-prose/references/WRITING-TECHNIQUES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Writing Techniques

Treat these as available tools. Choose a technique because of the job it performs, not because varied prose must contain it.

## Orient the reader

- **Direct opening:** State the point or problem when the reader needs immediate utility. Avoid generic scene-setting.
- **Narrative opening:** Begin with a real supplied moment or concrete case when experience will make an abstract subject tangible. Do not invent an anecdote.
- **Reader question:** Surface a genuine objection, invite a useful prediction or create a transition the answer fulfils. Avoid stock questions and empty requests for engagement.

## Explain and persuade

- **Example:** Make a general claim inspectable. Include the boundary that prevents the example from becoming a false universal rule.
- **Comparison:** Name the criterion, show the relevant alternatives and explain the consequence of the difference.
- **Analogy:** Map an unfamiliar idea to a familiar one, state where the mapping stops and retire it once direct explanation can carry the point.
- **Quotation:** Use exact words only when their wording or speaker matters. Attribute, contextualise and interpret them; paraphrase when only the information matters.
- **Direct address:** Use _you_ for a real reader action or relationship and _we_ only for genuine shared ground. Avoid synthetic intimacy or presumed agreement.

## Control pace and emphasis

- **Sentence contrast:** Give explanation room, then use a short sentence to land a real conclusion. Do not manufacture a short-long-short pattern.
- **Parallel phrasing or a triad:** Clarify genuinely comparable ideas or create a brief cadence. Do not pad a list to three or repeat the same pattern nearby.
- **Fragment, one-sentence paragraph or repetition:** Reserve it for an emphasis the surrounding prose has earned.
- **Humour or an aside:** Add local warmth or relief when it fits the writer's role and subject. Keep it subordinate to the message.

## Expose structure

- **Heading:** Name a useful stage or question in a longer piece. Avoid uniform template headings that could belong to any subject.
- **Bullets:** Use for related items readers may scan independently.
- **Numbers:** Use for sequence, rank or a fixed count.
- **Prose:** Keep connected reasoning in sentences and paragraphs when relationships and qualification matter more than item retrieval.

Use punctuation to show relationships and pace. A full stop can isolate a conclusion, a colon can introduce an explanation and a semicolon can hold close independent clauses together. Use an em dash sparingly for a distinct interruption or aside; when several appear, check whether full stops, commas, colons or parentheses express the relationships better.