webjs-blog-write

Write a webjs blog post

The repo publishes engineering blog posts from the repo-root blog/ directory. The website reads them directly (website/modules/blog/queries/list-posts.server.ts, BLOG_DIR = <repo>/blog), parses the front matter, and sorts by date descending. A post is one markdown file at blog/<slug>.md. This skill is how a new post lands in the author's voice, ranks for search, and states only claims that are actually true, without a later cleanup pass.

Step 0 (mandatory, do this FIRST): analyze the author's current style

Do NOT write from a fixed style spec. The voice is defined by the corpus, and the corpus changes over time, so a hard-coded spec goes stale. Before writing a single sentence:

1. Read a broad sample of blog/*.md (at least six to eight posts spanning different topics and dates, including the two or three most recent by date). Read whole posts, not just the openings.
2. From that reading, note for yourself: how the author opens a post, how paragraphs are paced, how code is introduced, how sections are titled, how a post closes, and which words and rhythms recur. The sections below capture what has been true so far, but the corpus you just read is the authority. If it has drifted from this description, follow the corpus and update this skill.

The patterns that have held so far (confirm them against what you read):

• First person, opinionated, honest. The author writes as themselves ("I wanted the opposite", "kept biting me", "I did not find one I enjoyed using"). Personal origin and motivation are welcome.
• A concrete hook, never a definition. Posts open on a scenario, an attack, a painful task, or a plain-language framing, not on "X is a...". A handful of posts use a signature "Let me start with..." or "Let me show you" opener; keep that phrasing where the author reaches for it, but the dependable pattern is the concrete hook itself, not the specific words.
• Beginner-friendly. Every acronym or jargon term is expanded in parentheses on first use, for example "SSR (server-side rendering)" or "an async generator (a function that yields values over time instead of returning once)".
• Second person in walkthroughs. Once into the mechanics, the author addresses "you" and shows real ts / sh code blocks.
• The painful old way, then the WebJs way. Most feature posts show the tedious status-quo pattern first (a useEffect + spinner, thirty lines of optimistic bookkeeping, a native-addon compile), then the WebJs version that removes it.
• Section headers are single #, sentence case, often with a trailing clause. For example "# The classic answer, and why it is fiddly" or "# What the sourcemap layer cost".
• Length runs substantial, commonly around 1000 to 1600 words, with deeper posts closer to 2200. Match the length of comparable posts you read in Step 0. Substance over padding, and never pad to hit a number.
• Vary the closing. Do NOT reach for a generic "# The takeaway" header. A closing header that repeats verbatim across the blog is the clearest formulaic tell there is, no matter how good each post is on its own. Most posts should just land their point in the final paragraph with no labeled closing section at all. When a post does want a labeled close, give it a header specific to that post's argument, and check that no other post already uses it. Treat any header that shows up on more than one or two posts as a smell.
• Contrast with the tool the reader knows. React, Next.js, Rails, Lit, Remix, Astro. Explain what that tool does and why WebJs chose differently, on WebJs's own terms.