Skip to content

angushushu/shu-academic-writing-skill / core/polish-prose

polish-prose

Verified

Diagnose why prose is hard to read at the sentence and paragraph level, using Joseph Williams's principles — characters as subjects, old before new, the stress position, topic strings, nominalization, hedging, and passive voice used fairly. Use when someone wants writing tightened, clarified, or line-edited, or asks why a passage feels dense, clunky, wordy, stiff, bureaucratic, or hard to follow — methods sections, technical documentation, reports, memos, cover letters, grant prose, and emails, not only academic papers. Also use when someone asks how to cut length without losing content or how to make an already-sound argument easier to read. Default behavior is naming patterns with quoted evidence and drills, not rewriting. If the draft's argument or contribution is what is actually in question, `core/engineer-argument/SKILL.md` handles that layer first.

FileKindSize
SKILL.mdskill md11.8 KB
references/drills.mdmarkdown4.8 KB
references/sentence-craft.mdmarkdown9.5 KB
references/style-guide.mdmarkdown2.7 KB

references/drills.md

View on GitHub
# Drills

A diagnosis fixes one passage. Drills change a writer. Assign **two or three**, matched to the
patterns you named — a list of eight exercises gets skipped entirely.

Each drill states the habit it treats, what the author does, and how they know it worked. Give
the drill in their own terms; don't just paste the name.

The point of every one of these is the same: make the author *see* the pattern in their own
prose without you pointing at it. That's the skill that transfers to the next draft.

---

## 1. Subjects and verbs

**Treats:** nominalization clusters, hidden agents, abstract subjects.

Take one page. Underline the grammatical subject and main verb of every sentence. Read only
those pairs aloud.

You should hear characters doing things. If you hear "analysis was conducted," "consideration
is given," "the relationship exists" — the actors are missing, and the reader is reconstructing
them on your behalf.

**Done when:** most subject-verb pairs name someone or something doing something.

## 2. The first five words

**Treats:** old-before-new violations, choppy paragraphs, sentences with nothing to attach to.

Underline the first five words of every sentence in one paragraph. Each should contain
something from the sentence before — a repeated term, a pronoun pointing back, a summarizing
noun.

Where the link is missing, you've asked the reader to hold new material with nowhere to put it.

**Done when:** you can trace a chain of shared terms from the paragraph's first sentence to its
last.

## 3. The last four words

**Treats:** wasted stress positions, trailing citations, emphasis on qualifications.

Read only the final four words of every sentence in a key paragraph. That list is what your
reader carries forward.

If it's mostly citations, "in this context," and "to some extent," the emphasis positions are
being spent on furniture.

**Done when:** the list reads as the paragraph's substance.

## 4. The paragraph subject list

**Treats:** scattered paragraphs where every sentence is individually clear.

List the grammatical subject of every sentence in one paragraph. If the list contains more than
two or three distinct topics, the paragraph is doing more than one job — and a reader has no
way to say afterward what it was about.

Caveat worth respecting: a paragraph tracking a genuinely complex relation may shift subjects
deliberately. Judge by whether a reader could state the topic afterward, not by the count.

**Done when:** the subject list names one thing, or one thing and its parts.

## 5. Verb by word twelve

**Treats:** long opening clauses, delayed verbs, suspended judgment.

Find every sentence where the main verb arrives after word 12. For each, ask what is sitting in
front of it and whether that material could follow the verb instead.

**Done when:** the reader learns what the subject is *doing* before they've forgotten what the
subject was.

## 6. The deletion test for openers

**Treats:** throat-clearing, metadiscourse that substitutes for the claim.

Delete every "It is important to note that," "It should be emphasized that," "There are several
factors which," and "In order to" from one section. Read it again and mark which sentences lost
anything.

Keep the signposting that helps a reader navigate a long document — "I turn now to the second
condition" earns its space. Cut the openers that announce a claim instead of making it.

**Done when:** the surviving openers all carry content.

## 7. The hedge audit

**Treats:** hedge stacking, claims the author doesn't sound willing to make.

Find every sentence with two or more hedges. For each, ask: what exactly am I uncertain about?
Keep the hedge that names that specific limit; drop the rest.

Some venues require heavy modality — check what comparable published work does before cutting
on principle. What is never idiomatic anywhere is the stack.

**Done when:** every remaining hedge marks a limit you could defend if asked.

## 8. The claim in twenty words

**Treats:** overlong central claims, buried thesis, no sentence that lands.

Write the passage's main claim in twenty words or fewer, as a single sentence, with no hedges.
Then decide which hedges to add back and name what each one is protecting against.

**Done when:** the twenty-word version is defensible and you can say precisely what each
restored qualifier does.

## 9. The hidden agent hunt

**Treats:** passives that conceal choices the reader needs to evaluate.

For every passive construction in your results and discussion, ask whether the hidden agent is
you. "Three sites were excluded" hides who excluded them and why — precisely what a skeptical
reader wants.

Leave the passives where the recipient is genuinely the topic, or the agent genuinely doesn't
matter. Methods sections are full of correct passives.

**Done when:** no passive in the draft hides a decision you made.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall