# Eloquent Science

> Apply the principles of Eloquent Science to scientific and technical writing. Use when drafting, structuring, or revising research papers, abstracts, titles, figures/tables, or conference talks; when reviewing a peer's manuscript; or whenever the user wants clearer, more concise, publication-quality scientific prose. Works for any technical discipline.

- Skill: `yuanzhao321/eloquent-science` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add yuanzhao321/eloquent-science`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yuanzhao321/eloquent-science/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: yuanzhao321 (https://skillmd.com/u/yuanzhao321)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yuanzhao321/eloquent-science

---


# Eloquent Science

A practical system for writing, revising, and presenting science clearly.

Use it to draft from scratch, to diagnose and fix a weak draft, to design figures,
to prepare a talk, or to review someone else's manuscript. The advice generalizes
to any technical field; substitute your own domain for the meteorology examples.

## Core philosophy

Scientific writing is not literary writing. Its job is to transfer understanding to a
reader as efficiently and unambiguously as possible. Two words govern everything:

- **Concision** — say it in as few words as possible.
- **Precision** — say *exactly* what you mean, no more, no less.

Organizing metaphor is the **writing/editing funnel**: work from the
largest scale down to the smallest, and revise in the same order.

1. **Document** — does the paper have a clear story, the right structure, the right journal?
2. **Sections** — is each section doing its job and in the right order?
3. **Paragraphs** — is each unified, coherent, and connected to its neighbors?
4. **Sentences** — active, direct, varied, no wasted clauses.
5. **Words** — concise, precise, the right term every time.
6. **Mechanics** — grammar, punctuation, spelling, formatting, references.

Never polish words before the structure is sound. Fixing a sentence inside a
paragraph that shouldn't exist is wasted effort.

## Workflow

**Drafting a new paper or section**
1. Decide whether the science is publishable and who the audience is. Pick the target journal *before* writing — it sets scope, length, and style.
2. Brainstorm and outline before drafting. Get a skeleton of sections and the one-sentence claim of each paragraph.
3. Write a fast, ugly first draft. Lower the hurdle: silence the inner editor, write badly, fix later. Momentum beats perfection.
4. Then run the funnel from the top down.
→ See `references/paper-structure.md` for what each section must contain.

**Revising / fixing a draft**
1. Read top-down through the funnel; fix large problems before small ones.
2. List every section/subsection heading on one page — does the outline alone tell the story? Are headings parallel and descriptive?
3. Check each paragraph for one idea + coherence (repetition, enumeration, transition).
4. Tighten sentences: prefer active voice, action verbs, short subject–verb distance.
5. Cut wordy phrases and weak words; verify every term is precise.
6. Aim to cut length — a tightened draft is often 10–20% shorter and clearer.
→ See `references/revision-checklist.md` for the full pass-by-pass checklist.

**Reviewing someone else's manuscript**
→ See `references/peer-review.md`.

**Preparing a talk**
→ See `references/presentations.md`.

## The highest-leverage habits

These fix the majority of weak scientific writing. Apply them first.

- **One idea per paragraph.** 4–8 sentences is the sweet spot. Avoid single-sentence paragraphs. Open with a topic sentence that states the paragraph's claim.
- **Connect paragraphs deliberately.** Coherence comes from *repetition* of key terms, *enumeration* (first, second, third), and *transition* words. The reader should never wonder why a paragraph follows the one before it.
- **Prefer active voice and action verbs.** "Raleigh reported light snow," not "Light snow was reported at Raleigh." Kill weak verbs (is, are, occur, exist, was observed); choose verbs that carry the action.
- **Put the action in the verb, the actor in the subject.** Avoid nominalizations: "we compared," not "we performed a comparison of."
- **Cut empty phrases.** "to" not "in order to"; "because" not "due to the fact that"; "near" not "in the vicinity of." → full table in `references/word-usage.md`.
- **Be precise, not vague.** Replace "Differences between two models are examined and discussed" with the specific finding. Vague sentences are worthless.
- **Lead the introduction with a hook.** Establish common ground, then state the conflict/gap (a paradox, error, or missing knowledge), then your response. No conflict = no reason to read on.
- **Vary sentence length and rhythm.** All-short sounds childish; all-long exhausts. Mix them.

## Reference files

Load the relevant file when the task calls for it:

- `references/paper-structure.md` — title, abstract, keywords, introduction, methods, results, discussion, conclusions, acknowledgments, references; what each must contain and common failure modes.
- `references/clear-writing.md` — paragraph coherence, sentence construction, active/passive decision table, verb choice, parallelism, modifiers.
- `references/word-usage.md` — concision (wordy phrase → short alternative table), words to avoid, precision pitfalls, weak nouns/verbs.
- `references/figures-tables.md` — designing figures, captions, fonts, color, tables vs. figures, citing the literature.
- `references/revision-checklist.md` — the funnel as an actionable, ordered checklist plus authorship and ethics reminders.
- `references/presentations.md` — focusing the message, slide design, opening/closing, timing, nervousness.
- `references/peer-review.md` — how to read, structure, and write a constructive review; reviewer obligations.

## Quick diagnostic prompts

When asked to improve a passage, run these checks and report concrete edits:

1. What is the one claim of this paragraph? If you can't say it, the paragraph needs splitting or refocusing.
2. Where is the passive voice, and would active be stronger here?
3. Which words can be cut with no loss of meaning?
4. Is every term precise, or is something vague/ambiguous?
5. Does this connect to what came before (repetition/transition)?
6. Read it aloud — does the rhythm vary, or does it plod?