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-writingwhen claims require external or primary evidence; - use
ai-devblogfor technical story selection and publication; - use
ai-readmefor executable repository documentation; - use
person-profile-writingfor biographies and identity research; - use
video-talk-to-essayfor 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; - obvious or repetitive disclaimers that tell readers a game's money is fictional, an example is made up, or a model is synthetic. Put consequential assumptions and shipped-versus-planned status where they help a decision; don't keep announcing what the reader already understands;
- 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, orthis underscores; delve,leverage,foster,robust,seamless, and other prestige words when an ordinary verb says more;authority,boundary,contract,receipt,durable,surface, andexactused 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.
For example, prefer X founded Y to build inference software to The conference biography identifies X as the founder of Y, when the role is supported. A company
profile explains its products and work; the supplied recording does not establish broader archive coverage belongs in an internal coverage note. A biography selects
what a technical contribution reveals about the person; the presentation’s sequence
of tuning steps belongs on the talk page. These are selection examples, not fixed
sentence templates or permission to remove material uncertainty.
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
- 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.
- Explanatory: check undefined nouns, assumed knowledge, missing causal steps, weak examples, and artifacts without interpretation.
- 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. Use the writers' decisions as inspiration; never imitate their surface persona.
