style-editing
Apply Joseph Williams' clarity principles when writing or editing prose. Use when drafting technical or business writing, diagnosing unclear sentences, rewriting passive or abstract prose, or any time the user references Williams, "Style: Lessons in Clarity and Grace," or "Style: The Basics of Clarity and Grace.
git clone --depth 1 https://github.com/Agenta-AI/agenta /tmp/style-editing && cp -r /tmp/style-editing/.agents/skills/style-editing ~/.claude/skills/style-editingSKILL.md
# Williams' Style: Clarity and Grace
Practical principles from Joseph M. Williams' *Style: Lessons in Clarity and Grace* (and the condensed *Style: The Basics of Clarity and Grace*). Use as a checklist when writing or editing prose that needs to be clear, direct, and reader-friendly.
## Core philosophy
Williams' two foundational claims:
1. It is good to write clearly.
2. Anyone can write clearly, if they revise with the right principles in mind.
Skilled writers don't *write* clear sentences. They *revise into* them. Treat first drafts as raw material. Apply these principles in revision passes.
Clarity is reader-first: your job is to make the reader's work easy.
## The two foundational principles
### 1. Characters as subjects, actions as verbs
The grammatical subject of a sentence should name the actual character (the agent doing something). The verb should name what that character does.
When the subject is an abstraction and the verb is weak, the sentence loses energy and clarity.
- Bad: *"There was a decision by the committee to approve the budget."*
- Good: *"The committee decided to approve the budget."*
- Bad: *"The intention of the team was the implementation of a new policy."*
- Good: *"The team intended to implement a new policy."*
Diagnostic question for any unclear sentence: **Who is doing what?** If the answer is buried in nouns and prepositions, rewrite so the actor is the subject and the action is the verb.
### 2. Avoid nominalizations
A nominalization is a verb (or adjective) converted into a noun. They drain action from prose.
Common signs:
- Words ending in -tion, -ment, -ance, -ence, -al, -ity, -ness in subject position
- Phrases like "make a decision," "conduct an analysis," "give consideration to"
Rewrites:
- "Make a decision" → "decide"
- "Conduct an analysis of" → "analyze"
- "Give consideration to" → "consider"
- "Reach an agreement" → "agree"
- "Have a discussion about" → "discuss"
When you spot a nominalization in subject or object position, ask: can I turn it back into a verb and find a real character to do it?
## Voice and emphasis
### 3. Active over passive (with exceptions)
Default to active voice. Use passive only when:
- The agent is unknown ("My car was stolen.")
- The agent is unimportant or obvious
- You need to keep the subject consistent across sentences (cohesion — see below)
- You want to put the agent at the end of the sentence for emphasis (stress position)
Active voice puts the character first, where the reader expects to find it.
### 4. Stress position: end of sentence carries weight
Readers feel the natural emphasis of a sentence at its end. Put the most important new information there.
- Weak: *"Climate change is the most pressing issue facing humanity, in my opinion."*
- Strong: *"In my opinion, the most pressing issue facing humanity is climate change."*
- Weak: *"Agenta is the AI reliability layer that closes that gap, fundamentally."*
- Strong: *"The gap is what Agenta closes."*
When revising, ask: what's the most important word or idea in this sentence? Is it landing in the stress position?
## Cohesion across sentences
### 5. Old before new
Each sentence should start with information the reader already knows (from the previous sentence or shared context) and end with new information. This creates a chain readers can follow effortlessly.
- Choppy: *"Photosynthesis converts sunlight to energy. The Calvin cycle is the second stage of photosynthesis. Carbon fixation happens in the Calvin cycle."*
- Cohesive: *"Photosynthesis converts sunlight to energy. The second stage of photosynthesis is the Calvin cycle, which fixes carbon."*
In the cohesive version, each sentence picks up where the last one left off.
### 6. Topic strings (consistent subjects across a paragraph)
A paragraph has a "topic string" — the chain of grammatical subjects across its sentences. When the topic string is consistent, the paragraph feels unified. When subjects keep changing, the paragraph feels scattered.
Diagnostic: list the grammatical subject of each sentence in the paragraph. If the list is "team / data / system / users / process / our approach," the paragraph has no topic string. Pick one anchor character (often the most important agent in the paragraph) and rewrite so most sentences share that subject.
This is what passive voice is good for: it lets you keep the same subject across sentences even when the action changes hands.
### 7. Topic + body + close in paragraphs
Each paragraph should:
- Open with a controlling sentence (the issue or claim)
- Develop it in the body
- Close with a sentence that points forward, names the consequence, or summarises
Don't bury the controlling idea in the middle. The opening sets the topic; the close earns the stress position.
## Concision
### 8. Cut what you don't need
Williams' favourite categories of cuts:
**Wordy phrases:**
- "due to the fact that" → "because"
- "in order to" → "to"
- "at this point in time" → "now"
- "for the purpose of" → "to"
- "in the event that" → "if"
- "with regard to" → "about"
- "the fact that" → usually deletable
**Doublets** (keep one of each pair):
- "each and every"
- "first and foremost"
- "any and all"
- "true and accurate"
**Empty modifiers:**
- very, really, basically, actually, literally, essentially, simply, quite, rather
**Throat-clearing openers:**
- "I think that..."
- "It should be noted that..."
- "It is important to remember that..."
**Redundant pairs:**
- "free gift" (gifts are free)
- "advance planning" (planning is in advance)
- "end result" (results are at the end)
### 9. Sentence length: vary it on purpose
Mix short and long sentences. A short sentence after a long one creates emphasis. A run of short sentences in a row gets choppy. A run of long sentences in a row gets exhausting.
Read your prose aloud. The rhythm should breathe.
## Grace (the optional layer)
### 10. Parallel structure
When you list or contrast, use parallel gramHelps add announcement cards to the sidebar banner system. Use when adding changelog entries, feature announcements, updates, or promotional banners to the Agenta sidebar. Handles both simple changelog entries and complex custom banners.
Playbook for adding a new coding-agent harness to Agenta (Codex, Hermes, Gemini, OpenCode, ...). Use when starting, planning, or reviewing a new-harness project. Covers the readiness audit of prior art, the spike-first milestone plan, the full integration-surface checklist, the per-harness variance axes to probe, and the process/communication contract with Mahmoud. Living document: every harness project appends its lessons to resources/LESSONS.md.
>-
Where to put frontend code (package vs app layer) and how to use the @agenta/* packages. Use when authoring or moving code in web/packages, choosing between @agenta/ui, @agenta/entities, @agenta/entity-ui, @agenta/shared, @agenta/playground, using molecules, loadable/runnable bridges, the EntityPicker, or writing package unit tests.
Use this skill to create and publish changelog announcements for new features, improvements, or bug fixes. This skill handles the complete workflow - creating detailed changelog documentation pages, adding sidebar announcement cards, and ensuring everything follows project standards. Use when the user mentions adding changelog entries, documenting new features, creating release notes, or announcing product updates.
Hard-won GitButler mechanics for multi-lane work in this repo — committing to a specific lane in a stack, spreading a pile of edits back across an existing stack, ordering a stack and setting PR bases, and recovering from a scrambled workspace. Use when working with stacked branches, when `but rub`/`but absorb`/`but commit --only` mis-routes a change, when a stack collapses or a commit lands on the wrong lane, or when a hunk gets dropped. Not needed for ordinary single-lane work.
Drive a researched and planned feature to a landed, tested change. Use after plan-feature has produced a docs/design/<project>/ workspace and the user says "implement it", "build the plan", "run the plan", or "let's ship this". Orchestrates refresh-plan, implement, review, a debug-local-deployment loop, and a test loop across the daytona / local-pi / claude x SDK / UI matrix, then documentation and a GitButler stacked branch. The orchestrator stays in the loop and spins narrow subagents for each phase.
Feature-folder layout, states/ convention, and data-flow rules for the Agenta mobile app (web/mobile). Use when creating or moving files under web/mobile, deciding where a component lives, adding a new feature or screen, or wiring data into mobile components.