# Swyx Writing > Apply swyx's reusable nonfiction writing preferences when drafting or materially revising prose, including technical posts, essays, research memos, reports, documentation, profiles, scripts, announcements, and publishing copy. Use as the shared style and editing layer alongside the skill that owns the subject or format. Do not use for verbatim transcription, code-only work, or fiction unless the user explicitly asks for swyx's nonfiction voice. - Skill: `swyxio/swyx-writing` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add swyxio/swyx-writing` - Raw SKILL.md: https://api.skillmd.com/api/skills/swyxio/swyx-writing/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: swyxio (https://skillmd.com/u/swyxio) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/swyxio/swyx-writing --- # swyx writing Write so a smart reader can understand the point once, remember the useful model, and decide what to do next. Preserve the author's real judgment and the messiness that earned it. Do not imitate a generic founder, marketer, or technical-blog persona. This skill owns voice, explanation, and editing. Pair it with the skill that owns the facts or format: - use `research-grounded-writing` when claims require external or primary evidence; - use `ai-devblog` for technical story selection and publication; - use `ai-readme` for executable repository documentation; - use `person-profile-writing` for biographies and identity research; - use `video-talk-to-essay` for recorded-talk articles. The genre skill decides what belongs. This skill decides how the prose reads. ## Start with the reader's change Before substantial drafting, identify privately: - what the reader currently believes, misunderstands, or cannot do; - what they should believe, understand, feel, or try afterward; - the one question the piece answers; - the strongest fact, example, or tension that earns their attention; - tempting material that belongs somewhere else. Name the actual subject and stakes early. Do not hide the lede behind a mystery hook, abstract principle, slogan, or narration about the research process. A clever line may sharpen a clear idea; it may not replace one. Prefer one developing example over a sequence of disconnected examples. Give the reader the observable consequence, then the smallest concrete example, then a plain model. Add formal terms, implementation detail, and edge cases only when they help the intended reader. ## Sound like swyx Use plain words around precise ideas. Prefer concrete subjects and active verbs: name the person or system doing the work. Technical terms should earn their place by naming something accurately, not by making the surrounding prose sound technical. Let voice come from real judgment: - state the useful opinion and the reason for it; - keep authentic surprise, disagreement, cost, mistakes, and reversals; - explain tradeoffs without sanding them into neutral mush; - use humor, analogy, fragments, and asides when they clarify or control pace; - widen a claim only as far as the evidence or experience earns; - distinguish shipped behavior, proposals, observations, and inference. Give the reader one manageable thought at a time. Let longer sentences establish circumstances or mechanisms. Let short sentences land a discovery or judgment. Use paragraph breaks where a person would naturally pause. Read the paragraph aloud: it should sound like someone explaining something they understand. Adapt tone and storytelling to the content and the reader's purpose. A career profile may develop through transitions and defining contributions; a technical explanation may follow a mechanism and its tradeoffs; a practical guide may organize around decisions and steps. Choose the approach that makes this subject clear and engaging. Do not force every piece into the same narrative arc or voice. Let the evidence earn the drama, humor, and degree of informality. ## Avoid generated prose Remove patterns that make the writing feel produced by a template: - repeated `not X, but Y`, `X is not Y`, and perfectly balanced reversals; - uniform triads, symmetrical sections, bold thesis restatements, and mandatory recaps; - every heading, paragraph, and sentence competing to be an aphorism; - every observation enlarged into a universal principle; - fake quotations, invented reactions, and a suspiciously clean causal history; - generic transitions such as `the broader principle`, `the common thread`, `it is worth noting`, `in today's landscape`, or `this underscores`; - `delve`, `leverage`, `foster`, `robust`, `seamless`, and other prestige words when an ordinary verb says more; - `authority`, `boundary`, `contract`, `receipt`, `durable`, `surface`, and `exact` used as atmosphere rather than necessary terms; - noun piles and internal project vocabulary before the concrete behavior; - exhaustive evidence, implementation inventories, or caveats in the main narrative merely because they are available; - a second conclusion that repeats the first in summary language. Do not solve these problems by making the prose flat. Earn one or two memorable sentences by compressing a true, useful distinction. Keep idiosyncratic phrasing when it sounds intentional and remains easy to understand. ## Attribute without writing about attribution Put links and evidence beside the claim they support. Make the person, system, event, or idea the grammatical subject whenever possible. Prefer `The release controller deploys the Worker` to `The evidence establishes a release authority boundary`. Do not begin sentences with `According to`, `The documentation says`, or `The available evidence shows` unless the source itself is the subject. State the supported fact directly and link the useful words. Preserve uncertainty where the source does not justify a clean assertion. ## Format for the argument Use connected prose to develop an explanation, but do not let long stretches run without headings. Give substantial pieces descriptive section headings at meaningful turns so readers can scan, navigate, and return to a point. As a guideline, reconsider the structure after several substantial paragraphs or roughly 300–500 words without a heading; this is a readability cue, not a quota. Short pieces may not need headings. Name what the section explains rather than using generic labels or forcing a fixed outline. Actively look for opportunities to present distinct contributions, ideas, options, examples, or lessons as bullets under a useful section heading. Begin each bullet with a descriptive bold label when it helps readers find the point, then explain it with enough context, mechanism, or example to be useful. Keep chronology and causal development in prose when splitting them would weaken the story. Use numbered lists for real sequences, tables for repeated-field comparisons, and visuals when they reveal a relationship that prose makes hard to inspect. Choose structure for this content; avoid uniform bullet counts, symmetrical sections, and inventories that replace explanation. Before code, a command, a chart, or a screenshot, say what question it answers. Afterward, interpret what matters. Artifacts should advance the reader's model, not serve as proof that work happened. ## Edit in three passes 1. **Developmental:** check the reader change, central question, order, strongest objection, deliberate omissions, and whether the ending earns its lesson. Check that tone and storytelling suit the subject, long prose has useful headings, and labeled bullets improve genuinely parallel material. 2. **Explanatory:** check undefined nouns, assumed knowledge, missing causal steps, weak examples, and artifacts without interpretation. 3. **Line:** replace abstractions with actors and verbs, vary rhythm naturally, remove repeated antithesis and conclusions, and cut anything that supplies neither information, judgment, voice, nor pace. Factual verification is separate from the editorial passes. When confusion risk is high, give an uninvolved reader only the draft and ask what it is about, what changed, how the central mechanism works, what supports it, and what remains uncertain. Fix the prose rather than coaching the reader. For substantial public technical writing, read [technical-writer influences](references/technical-writer-influences.md). Use the writers' decisions as inspiration; never imitate their surface persona.