style-clarity-grace
Skill1 starsChanged 3 months agoMITView on GitHub
Reader-based revision from Joseph Williams's Style: Toward Clarity and Grace — characters as subjects, actions as verbs, topic/stress, cohesion, paragraph point, concision. Use when prose is turgid, academic, nominalized, or hard to follow even if "correct"; when the user cites Williams, clarity and grace, or asks why a sentence is muddy. Prefer elements-of-style for punctuation/usage; writing-prose for anti-slop tone; writer-style for a named voice; writing-technical for form. Prefer the writing hub when the writing path is unclear.
In this repository47 other files it gives its agents.
- data-apache-lakehouseSkill
- data-apiSkill
- dataSkill
- data-duckdbSkill
- data-identity-resolutionSkill
- data-pipeline-operationsSkill
- data-pokemon-tcg-foundationsSkill
- data-product-evalSkill
- data-reelsSkill
- data-semantic-qualitySkill
- data-table-lifecycleSkill
- html-designSkill
- ebay-listingSkill
- flutter-pro-ux-reviewSkill
- flutterSkill
- browser-testing-with-devtoolsSkill
- browser-verifySkill
- design-systemSkill
- frontend-designSkill
- mobile-app-echarts-visualSkill
- mobile-blog-chart-visualSkill
- mobile-chart-visualSkill
- mobile-product-uxSkill
- mockup-implementSkill
- product-designSkill
- product-ui-craftSkill
- prototypeSkill
- react-performanceSkill
- ui-exploreSkill
- visual-verifySkill
- web-qualitySkill
- high-retention-insight-reels-instagramSkill
- instagramSkill
- instagram-virality-insightsSkill
- marketing-cashvertisingSkill
- marketing-contagiousSkill
- marketing-going-viralSkill
- marketingSkill
- marketing-offersSkill
- marketing-storybrandSkill
- quality-checkSkill
- elements-of-styleSkill
- writer-styleSkill
- writing-docsSkill
- writing-proseSkill
- writingSkill
- writing-technicalSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
Do not restyle voice. Do not change frozen facts.
- Distinctive: line 34
After form/voice, before or instead of a blind Strunk cut
- Distinctive: line 93
Add or move the point sentence.
- Distinctive: line 108
Never chase balance before the reader can see the actor.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Style — clarity and grace
Job: Make the reader see who did what, in an order they can follow. Do not restyle voice. Do not change frozen facts.
Source: Joseph M. Williams, Style: Toward Clarity and Grace (University of Chicago Press, 1990; two chapters with Gregory G. Colomb). This skill distills the revision system. Do not quote the book or reproduce its examples at length.
Clarity: references/clarity.md
Cohesion + emphasis: references/cohesion-emphasis.md
Paragraph / document: references/coherence.md
Concision + long sentences: references/concision-shape.md
Real rules vs folklore: references/usage-real-vs-folk.md
When to load
- Draft exists and reads heavy, abstract, or “correct but exhausting”
- “This is muddy,” “too academic,” “can’t see the actor,” “Williams pass”
- After form/voice, before or instead of a blind Strunk cut
Not for: inventing a persona, picking a blog mode, writing a runbook from scratch, or landing-page conversion.
Core rule
Readers parse easily when subjects name characters and verbs name actions, familiar matter sits left (topic), and new/important matter sits right (stress). Telling someone “be clear” is useless. Diagnose the syntax, then revise it.
Passive is not the enemy. A dummy subject, a buried character, and a nominalized action are.
Revision workflow
Copy and track:
Williams pass:
- [ ] Diagnose subjects/verbs
- [ ] Characters → subjects, actions → verbs
- [ ] Topic left, stress right
- [ ] Paragraph has a point
- [ ] Concision (after shape)
- [ ] Facts unchanged- Diagnose. In each load-bearing sentence, mark the grammatical
subject and the main verb. If the subject is an abstraction
(
the implementation of…,there is) and the verb is empty (is,involves,has,occurs), the sentence is turgid. - Characters / actions. Who is doing what? Lift the character (person, system, named agent) into the subject. Lift the action (often a noun in -tion / -ment / -ance / -ing) into the verb. See clarity.md.
- Cohesion. End of sentence N should make the start of N+1 feel expected. Old/familiar → left. New/stress → right. See cohesion-emphasis.md.
- Coherence. A reader should be able to say the paragraph’s point in one sentence. Topics across the paragraph should be a short consistent set. See coherence.md.
- Concision last. Cut after the bones are right. Blind cutting makes unclear prose shorter, not clearer. See concision-shape.md.
- Return the edited text. List material syntactic changes, not every comma.
Fast checks (most turgid drafts fail these)
- Subject is a nominalization —
The analysis of the logs was performed by the on-call→The on-call analyzed the logs. - Empty verb —
A decision was made to…→We decided to… - Backwards information — new claim first, context last. Flip: context/topic left, payoff right.
- Subject–verb gap — a long aside between them. Move the aside or split the sentence.
- No paragraph point — a stack of true sentences that never land. Add or move the point sentence.
- Folklore enforcement — do not “fix” split infinitives, ending prepositions, or every passive. See usage-real-vs-folk.md.
Do not fight the other writing skills
| Keep | Do not “Williams away” |
| Frozen numbers, APIs, quotes | Smoother syntax that changes a claim |
writing-prose punches / seams | Uniform elegance |
| Passive when the receiver is the topic | Blind active-voice conversion |
| Useful nominalizations (already-known events used as topics) | Unpacking every -tion |
Clarity first, then cohesion, then concision, then (rarely) elegance. Never chase balance before the reader can see the actor.
Vs elements-of-style
| style-clarity-grace | elements-of-style | |
| Job | How readers parse; revise syntax | Usage + Strunk commandments |
| Passive | Keep when it topics the right thing | Prefer active, with the same exception |
| Concision | After characters/actions are right | Cut needless words as a first move |
| Load | Muddy / nominalized / hard to follow | Comma splices, danglers, padding |
Typical stack: this skill for shape, then elements-of-style for leftover mechanics.
Hand off
| Need | Skill |
| Punctuation / danglers / series comma | elements-of-style |
| Human tone / anti-slop | writing-prose |
| Named voice (default: Evan) | writer-style |
| Research / build-log form | writing-technical |
| Runbook / API reference | writing-docs |
| Offer / landing | marketing |
| Unclear writing path | writing hub |
Done criteria
- Load-bearing sentences: character in the subject, action in the verb
- Topic left, stress right; sentences chain
- Each paragraph has a namable point
- Shorter only where words did no work
- Facts and voice seams intact
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

