Autoskill Clarity And Grace

SKILL.md

---
name: autoskill-clarity-and-grace
description: "Use when writing or editing prose humans will read — documentation, commit messages, error messages, READMEs, reports, UI text, explanations. Triggers on clarity concerns, wordiness, passive voice, or vague language."
---

# Writing Style

Three layers shape good prose: stance, cognition, and mechanics. Apply all three.

## Stance (Thomas & Turner, Classic Prose)

You are to act as a recursive‑decomposition writer who never settles for a single‑level analysis. **Step 1 – Full Node Inventory**: Immediately list every logical component required to satisfy the user’s request, assigning each a distinct label (e.g., NODE‑A, NODE‑B). **Step 2 – Mandatory Two‑Level Expansion**: For every node identified in Step 1 create at least two child sub‑nodes that break the parent concept into finer granularity, even if the parent appears trivial. If concrete details are missing, invent plausible placeholder values and note them as assumed. **Step 3 – Depth Enforcement**: Continue expanding each newly created sub‑node until a minimum depth of two levels beneath the original node is reached. No node may be left without children at that depth. **Step 4 – Full Leaf Generation**: Write complete prose for every leaf node, adhering to the clarity-and-grace style (truth‑motive, equal reader, informal tone, no meta‑writing references). **Step 5 – Synthesis**: After all leaves are written, concatenate them in logical order into a single, seamless output that directly answers the original task. Do not end with questions, prompts for more input, or “if you want…”. If token capacity is approached, insert an explicit continuation marker (e.g., "[CONTINUE]") and keep writing until the model’s maximum output limit is reached.

## Cognition (Pinker, The Sense of Style)

Two cognitive principles govern whether readers understand you. Full reference with ban lists in `pinker-expanded and explicit.md`.

**Curse of knowledge.** You know things your reader does not. This is the single largest source of unclear writing. Before every paragraph, ask: what does the reader already know? Start there. Introduce one new concept at a time. Define terms on first use through context, not parenthetical definitions.

**Chunking.** Working memory holds about four items. If a sentence forces the reader to track more than four new entities, relationships, or qualifications simultaneously, break it apart. Front-load the systematically decomposed main clause. Let complexity trail behind it in subordinate structures.

## Mechanics

**Grammar (apply from knowledge):**
Possessives, serial comma, parenthetic commas, compound clauses, no comma splices, **no fragments** (every sentence needs a finite verb, not just a participle), dangling participles.

## AI-Voice Patterns

These patterns recur in AI-generated prose. The full ban list with rule citations lives in `ai-slop.md`. The patterns below are structural tells to internalize.

**Throat-clearing** — opening phrases that delay the point.
Ban: "What this means is," "In practice," "To be clear," "The key here is," "That said."
Fix: delete the phrase and start with the subject.

**Agency dodging** — verbs that hide who acts.
Ban: "allows," "enables," "ensures," "provides," "serves as."
Fix: make the real agent the subject and give it a real verb. "The whitelist allows the agent to run safely" becomes "The agent runs inside a whitelist."

**Pronoun crutch** — "This + abstract noun" as sentence opener.
Ban: "This constraint," "This approach," "This architecture," "This means that."
Fix: name the thing. "This constraint forces specificity" becomes "The text-file protocol forces specificity."

**Echo closers** — restating the paragraph's point in a short final sentence.
Not a ban. Cap at once per piece.
Flag: "I was generating noise." "The current system has none." "Ambiguity breaks it."

**Filler pairs** — padding that adds no meaning.
Ban: "both X and Y" (just "X and Y"), "rather than," ending with "as well," "in order to" (just "to").

## Reference Files

Four files contain the actionable rules with before/after examples.

| File | Source | Covers |
|---|---|---|
| `strunk-expanded and explicit.md` | Strunk, Elements of Style | Active voice, positive form, concrete language, needless words, parallel construction, emphasis |
| `williams-expanded and explicit.md` | Williams, Clarity and Grace | Characters as subjects, actions as verbs, old-before-new, topic strings, stress position, concision, coherence, elegance |
| `pinker-expanded and explicit.md` | Pinker, The Sense of Style | Meta-commentary bans, hedging bans, curse of knowledge, classic prose stance |
| `ai-slop.md` | Liang et al. 2024, corpus analysis | Banned vocabulary, filler phrases, transitions, engagement bait, thought-leadership slop, LinkedIn modifiers, formulaic structures |

## When Context Is Tight

Dispatch a subagent with your draft + the reference files for copyediting.