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.