agentleFS
Evan-Kim2028Evan-Kim2028/agent-skills/skills/writing/style-clarity-grace/SKILL.md

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.

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
  1. Distinctive:

    Do not restyle voice. Do not change frozen facts.

    line 17
  2. Distinctive:

    After form/voice, before or instead of a blind Strunk cut

    line 34
  3. Distinctive:

    Add or move the point sentence.

    line 93
  4. Distinctive:

    Never chase balance before the reader can see the actor.

    line 108

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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
  1. 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.
  2. 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.
  3. Cohesion. End of sentence N should make the start of N+1 feel expected. Old/familiar → left. New/stress → right. See cohesion-emphasis.md.
  4. 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.
  5. Concision last. Cut after the bones are right. Blind cutting makes unclear prose shorter, not clearer. See concision-shape.md.
  6. Return the edited text. List material syntactic changes, not every comma.

Fast checks (most turgid drafts fail these)

  1. Subject is a nominalization — The analysis of the logs was performed by the on-call → The on-call analyzed the logs.
  2. Empty verb — A decision was made to… → We decided to…
  3. Backwards information — new claim first, context last. Flip: context/topic left, payoff right.
  4. Subject–verb gap — a long aside between them. Move the aside or split the sentence.
  5. No paragraph point — a stack of true sentences that never land. Add or move the point sentence.
  6. 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

KeepDo not “Williams away”
Frozen numbers, APIs, quotesSmoother syntax that changes a claim
writing-prose punches / seamsUniform elegance
Passive when the receiver is the topicBlind 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-graceelements-of-style
JobHow readers parse; revise syntaxUsage + Strunk commandments
PassiveKeep when it topics the right thingPrefer active, with the same exception
ConcisionAfter characters/actions are rightCut needless words as a first move
LoadMuddy / nominalized / hard to followComma splices, danglers, padding

Typical stack: this skill for shape, then elements-of-style for leftover mechanics.

Hand off

NeedSkill
Punctuation / danglers / series commaelements-of-style
Human tone / anti-slopwriting-prose
Named voice (default: Evan)writer-style
Research / build-log formwriting-technical
Runbook / API referencewriting-docs
Offer / landingmarketing
Unclear writing pathwriting 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.