@tamng0905/builder-essential-skills 0.1.0

package/skills/write-blog/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: write-blog
+description: >-
+  Write and ship a blog post for your project that reads like a human wrote it and pulls
+  SEO traffic to your site. Use when a contributor wants to draft, edit, or publish a blog
+  post, add a post to the site, write about the project for search/traction, or make an
+  existing draft sound less like AI. Enforces the house voice (no em dashes), picks a
+  non-cannibalizing angle, wires the post into your site, and runs the humanizer pass
+  before shipping.
+compatibility: claude-code
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - AskUserQuestion
+---
+
+# Write a blog post
+
+You are helping a contributor write a blog post for the project's website. The bar: it
+reads like a person wrote it, it ranks for a search cluster no other post already owns,
+and it ships wired correctly into the site with the build green.
+
+This skill exists so every contributor writes in the same voice, picks non-overlapping
+topics, and passes the same anti-AI-slop gate, whether or not they already know the house
+rules.
+
+## The one rule that gets a post rejected
+
+**No em dashes (—) or en dashes (–). Ever.** The house voice bans them. Use a period, a
+comma, or "so"/"because"/parentheses instead. A single dash in a draft is a hard fail.
+There is a scanner: run `bash check.sh <file>` (in this skill's folder) on any draft before
+you call it done.
+
+## Workflow
+
+Do these in order. Don't skip the angle check or the humanizer pass.
+
+### 1. Read the ground truth first
+
+Before writing a word, read what already exists so you match voice and don't cannibalize
+keywords:
+
+- **Your site's post registry / index.** Whatever lists every published post (a registry
+  file, a content collection, a CMS list, or the frontmatter across your blog's source
+  directory). This is the **live record of every published post and the angle it owns.**
+  Read every slug, title, description, and tag set.
+- One or two full published posts (the prose sources) to absorb the voice.
+- `reference/angles.md` (in this skill folder) for how to pick an angle that doesn't
+  collide, plus the topics still untapped.
+- `reference/voice.md` for the house voice and the anti-AI checklist, self-contained.
+- `reference/craft.md` for the writing craft: leads that win the click, spine structure,
+  and which creative-writing skill to reach for at each stage.
+- `reference/seo.md` for on-page keyword placement, internal linking, verifying the
+  machine-readable SEO, and the post-ship distribution loop that earns the first backlinks.
+
+### 2. Pick and pitch the angle
+
+Every post must **own a distinct search cluster.** Two posts fighting for the same
+keywords cannibalize each other. From your post index and `reference/angles.md`, pick an
+angle no shipped post already owns, then pitch it back to the contributor in one line
+before drafting: the working title, the one-sentence thesis, and the 3-5 keyword phrases it
+targets. Confirm before you write the body. If they gave you a topic that collides with an
+existing post, say so and propose the adjacent-but-distinct angle instead.
+
+### 3. Outline
+
+A good post has a spine, not a listicle. Read `reference/craft.md` before you outline; the
+lead and the H2-spine are 80% of whether the post gets finished and ranked. Structure:
+
+- **A lead (description + opening) that names a concrete, specific problem** the reader has.
+  Not "AI agents are transforming collaboration." Something like "Two agents can talk about
+  a change all day. Handing over the change itself, byte for byte, is a different problem."
+- 4-7 sections, each with a claim and **real code, real commands, or a real number from
+  your project** backing it. Read the actual source and docs of your project and quote it
+  accurately. Made-up APIs are worse than no code.
+- A "what this is NOT" or honest-limitations beat. The voice is a little contrarian and
+  admits what's deferred. That honesty is what makes it not read like marketing.
+- A close that lands the thesis without a generic "in conclusion, the future is bright"
+  wrap-up. End on a concrete thing the reader can do or check.
+
+### 4. Draft
+
+Write the prose as plain markdown first, in your blog's source directory (the source of
+truth). Follow `reference/voice.md` and `reference/craft.md` as you write, so there's less
+to fix later. Keep it honest, concrete, and grounded in real project code. Vary sentence
+length. Have an opinion. If `/direct-response-copy` is available in your environment, run it
+on the title, description, and closing CTA (only those three surfaces, not the body).
+
+### 5. Humanize (mandatory)
+
+Run a humanizer pass on the draft: if `/humanizer` is available in your environment, invoke
+it on the draft. If it isn't available, apply the checklist in `reference/voice.md`
+yourself. Strip: significance inflation, promotional adjectives, the rule of three, "-ing"
+tail analyses, negative parallelisms ("it's not X, it's Y"), synonym cycling, hedging, and
+every dash. For headline/description/CTA polish you may also pull in
+`/direct-response-copy` if it's available.
+
+Then run `bash check.sh <draft-file>` and fix anything it flags.
+
+### 6. Wire it into the site
+
+Follow `reference/wiring.md`. In short: register the post in whatever index/registry your
+blog uses, add the body in your blog's format, make sure the SEO surfaces (sitemap, RSS,
+OG/Twitter cards, JSON-LD) include the new post, add the cover image, and build. For keyword
+placement (title/description/first-H2/tags), internal-link count, and anchor-text rules,
+follow `reference/seo.md`. Add a reciprocal inbound link from the most related existing post.
+
+### 7. Verify before done
+
+Your site's build command must be green. Then smoke-test the post: confirm the post page,
+the cover image, the blog index, the sitemap, and the RSS feed all load and include the new
+post. View source on the post and confirm the meta description, OG/Twitter tags, and
+`BlogPosting` JSON-LD actually emitted with the right values (`reference/seo.md` lists what
+to check). Re-run `bash check.sh` on the final markdown. Only then is the post itself done.
+
+### 8. Distribute (this is what earns the traction)
+
+A correct post with no inbound links does not rank. After it ships, seed the first signal:
+if `/x-tweet` is available in your environment, run it on the post's core insight for a
+thread that teaches the idea and links the post; cross-link the post from the relevant docs;
+and answer the real question it solves where people are already asking it. See the
+distribution loop in `reference/seo.md`. Always link the canonical production URL
+(`<your-site-url>/blog/<slug>`), never a staging or preview host.
+
+## Guardrails
+
+- Never invent project APIs, flags, or numbers. Read the source and quote it.
+- Never weaken the house voice to sound "professional." Concrete and a little contrarian
+  beats polished and generic every time.
+- Don't ship a post whose angle overlaps a published one. Adjust the angle instead.
+- Covers can be SVG or a raster image. Match your site's brand palette. If you can't make a
+  good cover, reuse an existing one rather than shipping something ugly.
+
+## Note on this skill's own files
+
+The scanner will flag `SKILL.md` and the `reference/` files because they name the banned
+characters `(—)` `(–)` and use `→` as teaching notation. That's expected. The scanner is
+for blog drafts and rendered post bodies, not for this skill's documentation.

package/skills/write-blog/check.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# check.sh — pre-ship scan for a blog draft.
+# Flags the house-style hard fails (em/en dashes, curly quotes, emoji) and the most
+# common AI-slop phrases so they get fixed before the post ships.
+#
+# Usage: bash check.sh <path/to/post>   (a markdown source or a rendered post body)
+# Exit:  0 = clean, 1 = hard issues found, 2 = bad usage.
+#
+# Unicode checks run through perl (portable across macOS BSD grep + Linux GNU grep,
+# which disagree on -P). Soft-phrase check uses portable grep -E.
+
+set -u
+
+file="${1:-}"
+if [ -z "$file" ] || [ ! -f "$file" ]; then
+  echo "usage: bash check.sh <file>" >&2
+  exit 2
+fi
+
+fails=0
+
+# perl_scan REGEX LABEL — print "line:text" for each matching line, count as a hard fail.
+perl_scan() {
+  local re="$1" label="$2" hits
+  hits="$(perl -CSD -ne 'print "    $.: $_" if /'"$re"'/' "$file")"
+  if [ -n "$hits" ]; then
+    echo "✗ $label:"
+    printf '%s\n' "$hits"
+    fails=$((fails + 1))
+  fi
+}
+
+# --- Hard fails: characters the house style bans -----------------------------
+perl_scan '[\x{2013}\x{2014}]' "em/en dash (— or –) — replace with a period, comma, or parentheses"
+perl_scan '[\x{2018}\x{2019}\x{201C}\x{201D}]' "curly quote (‘ ’ “ ”) — use straight quotes"
+perl_scan '[\x{1F000}-\x{1FAFF}\x{2600}-\x{27BF}\x{2190}-\x{21FF}\x{2B00}-\x{2BFF}]' "emoji / pictograph in prose"
+
+# --- Soft flags: common AI tells. Review each; not every hit is wrong. --------
+tells='testament to|pivotal|groundbreaking|seamless(ly)?|ever-evolving|evolving landscape|cutting-edge|game-chang|revolutioniz|underscor|it is (important|worth noting) to note|in conclusion|in order to|due to the fact|at this point in time|delve|leverage|robust and|it.s not just|isn.t just|serves as a|stands as a|plays a (vital|key|crucial) role|the possibilities are endless'
+soft="$(grep -nEi "$tells" "$file" 2>/dev/null)"
+if [ -n "$soft" ]; then
+  echo "⚠ possible AI-slop phrasing (review, don't blindly delete):"
+  printf '%s\n' "$soft" | sed 's/^/    /'
+fi
+
+echo
+if [ "$fails" -gt 0 ]; then
+  echo "FAIL: $fails hard-style issue group(s). Fix before shipping."
+  exit 1
+fi
+echo "OK: no hard-style issues. Still eyeball the ⚠ soft flags above."
+exit 0

package/skills/write-blog/reference/angles.md

@@ -0,0 +1,51 @@
+# Picking an angle that doesn't cannibalize
+
+The blog's job is SEO traction to your project and its site. That only works if each post
+owns a **distinct search cluster.** Two posts chasing the same keywords split their own
+ranking. So the first rule of a new post is: pick an angle no shipped post already owns.
+
+## How to check what's taken
+
+Your post registry / index is the live record. Read every title, description, and tag set
+before pitching. Each shipped post should own one spine, one topic cluster. Write down, for
+each existing post, the one search cluster it owns, then make sure your new angle sits in a
+gap between them, not on top of one.
+
+For example, on a developer-tool blog the shipped posts might each own a distinct spine: one
+on how the core mechanism works, one on a specific integration, a numbered "bugs that hid
+until production" war-stories post, a field-guide survey of the landscape, and a "why not
+just use X" honest-comparison post. A new post has to find the next gap, not re-litigate one
+of those.
+
+Always re-read the registry at write time; any list you wrote down earlier is a snapshot and
+the registry is the truth.
+
+## Finding an untapped angle
+
+Good starting points for a gap the existing posts don't cover:
+
+- **A deep dive on a subsystem no post has centered yet** (security/trust model, storage and
+  ops, a specific protocol or format). Check that a related post hasn't already spent the key
+  anecdotes; if it has, the new post needs a different spine.
+- **A "how we actually build this" process post** if the engineering workflow itself is
+  interesting and undocumented.
+- **An interoperability or integration story** that a broad post only mentioned in passing.
+- **An honest comparison** ("why not just use X") that no existing post has made head-on.
+
+Mine your own docs and issues for these. The best untapped angles are usually questions your
+users already ask that no post answers directly yet.
+
+## When to write a checklist / listicle instead
+
+Usually don't. The house format is a spine with a thesis, not a listicle. A "top N tools"
+post ranks briefly and ages badly, and it doesn't fit the voice. If a contributor wants one,
+steer them to a spine post on the same topic instead.
+
+## Keyword discipline
+
+- One primary phrase per post; put it in the `title`, the description (meta description),
+  the first H2, and the tags.
+- Pick phrases a real developer in your audience would type into a search box (an exact error
+  message, the plain name of a concept, a comparison like "X vs Y"), not brand-y phrases
+  nobody searches.
+- Internal-link to 1-2 sibling posts so ranking flows between them instead of competing.

package/skills/write-blog/reference/craft.md

@@ -0,0 +1,94 @@
+# Writing craft: make a technical post that people finish
+
+The house voice (`voice.md`) tells you what to strip. This file tells you what to build. A
+post that ranks but reads like a spec sheet gets a 90% bounce and never earns a backlink.
+Craft is what turns a correct post into one people finish and share.
+
+Study the shipped posts before you write. They are the ground truth for the craft, not this
+file. Read two full ones from your blog's source and notice what they actually do.
+
+## The lead is 80% of the job
+
+Most readers decide in the first two sentences. The lead is also your meta description and
+your search snippet, so it does double duty. Every shipped lead names a concrete, specific
+problem the reader already feels, with zero throat-clearing.
+
+- War-story open: `"A WebSocket that passed every localhost test and died the moment it
+  spoke TLS."` A single failing scene, not a topic sentence.
+- Tension open: `"Two agents can talk about a change all day. Handing over the change
+  itself, byte for byte, is a different problem."` State the easy thing, then the hard thing.
+- Contrarian open: `"AI agent memory in 2026 is mostly single-player."` A claim someone
+  could disagree with.
+
+Bad leads announce the topic ("In this post we'll explore agent memory"). Good leads drop
+the reader into a problem mid-scene. If your lead would survive being pasted into a search
+result as the one line that wins the click, it's ready. This is where `/direct-response-copy`
+earns its keep: run it on the title and lead specifically.
+
+## Structure is a spine, not a pile
+
+A ranking technical post is an argument that moves. Each section advances one claim and
+hands off to the next. The test: read only your H2s in order. Do they tell a story on their
+own? If they read like a glossary ("Overview", "Architecture", "Details", "Conclusion"),
+the spine is missing. Rewrite the H2s to be claims: "Identity is not authorization",
+"One SQLite file, two search engines".
+
+Proven shapes:
+
+- **Problem to mechanism.** Name the pain, show the naive fix, show why it breaks, show the
+  real mechanism with code.
+- **Numbered war stories.** N self-contained bug narratives, each with a one-line lesson,
+  bound by a theme. Scannable and linkable.
+- **Field guide.** Survey the landscape honestly, then place your thing inside it. Earns
+  authority because it credits the alternatives.
+
+## Show the machine
+
+The single biggest credibility lever in a technical post is real code, real commands, real
+numbers from your project, quoted accurately. Read the actual source and docs of your
+project and paste the actual thing. A reader who spots one invented API stops trusting the
+whole post. One accurate 8-line snippet beats three paragraphs describing it.
+
+Give every code block a job. Don't paste code and move on; the sentence before it says what
+to watch for, the sentence after says what just happened. Numbers are strongest of all:
+"buffers the whole blob in RAM" is fine, "buffers the whole blob in RAM, so a 200MB bundle
+is 200MB resident" lands.
+
+## Rhythm and voice
+
+- Vary sentence length on purpose. A four-word sentence after a long one is a drum hit. If
+  every sentence is the same length the reader's eye glazes; the humanizer will not catch
+  monotony, only you will. Read it out loud.
+- Have exactly one opinion per post and defend it. Contrarian-but-earned is the house
+  register: "most guides get this wrong" only works if you then show why, with code.
+- Admit what's deferred. A limitations beat ("what this is NOT") is the reason the post
+  reads like an engineer wrote it and not marketing. Candor converts.
+- First person when it fits. "I shipped this and it warmed up my laptop" beats "the system
+  experienced elevated CPU utilization."
+
+## Close on a next action, not a summary
+
+Never end with "in conclusion, as agents evolve, the possibilities are endless." End on one
+concrete thing the reader can do or check right now: a command to run, a file to read, a
+repo to clone, a claim to go verify. The close is where you convert a reader into a repo
+star or a hub signup, so make it a door, not a wall.
+
+## Which creative skill to reach for, when
+
+These are optional helper skills; use them if available in your environment.
+
+- `/humanizer`: mandatory pass on the finished draft. Strips AI tells. This is the gate
+  in the main workflow. If it isn't available, apply the checklist in `voice.md` by hand.
+- `/direct-response-copy`: the title, the description/lead, and the closing CTA. Use its
+  framework vocabulary (a promise, a specific mechanism, a reason to act now) on those three
+  surfaces. Do not let it inflate the body into ad copy; the body stays plain and technical.
+- `/x-tweet`: after the post ships, for the distribution thread that seeds traction. See
+  `seo.md`. A post nobody links to does not rank.
+
+## The finish test
+
+Read the whole thing out loud once. Three failure modes to catch: it sounds like a
+Wikipedia intro (clean but no pulse: add an opinion or a war story), it sounds like a sales
+page (promotional: cut adjectives, add code), or you got bored reading it (the spine
+sagged: find the section that repeats the one before it and cut it). Only ship a post you
+would actually finish reading.

package/skills/write-blog/reference/seo.md

@@ -0,0 +1,116 @@
+# Technical SEO + distribution: get the post found and linked
+
+`angles.md` covers not cannibalizing your own posts. This file covers the on-page mechanics
+that make a single post rank, and the distribution loop that gets it the first backlinks so
+it can rank at all. Ranking is on-page correctness times off-page signal; skip either half
+and the post sits on page 5.
+
+## On-page: one primary phrase, placed deliberately
+
+Pick one primary keyword phrase per post, the exact string a developer in your audience
+would type into a search box. Favor:
+
+- **Real error strings** (an exact message a user would paste): low volume, near-zero
+  competition, high intent. These are the cheapest wins.
+- **Concept phrases** (the plain name of the thing your post explains).
+- **Comparison phrases** ("X vs Y", "alternative to Z").
+
+Avoid brand-y phrases nobody searches ("the such-and-such paradigm"). You cannot rank for
+demand that does not exist.
+
+Place the primary phrase in all four of these, or the post is under-optimized:
+
+1. The post `title` (the `<title>` and OG title derive from it).
+2. The description / standfirst (the meta description and search snippet). Front-load the
+   phrase; make it a promise.
+3. The first H2 in the body.
+4. The tags/keywords (these become the JSON-LD `keywords`).
+
+Use secondary phrases naturally in later H2s. Do not stuff; modern ranking reads for
+coverage of a topic, not keyword density. One clear primary plus honest depth beats
+repetition.
+
+## On-page: the structural signals
+
+- **Sentence-case headings that are claims**, not labels. They double as the spine (see
+  `craft.md`) and as the outline Google reads.
+- **Deep-linkable H2s.** Every H2 needs an `id` so sections can be shared and can
+  win their own snippet.
+- **Internal links: 2 to 3 per post**, to sibling posts by `/blog/<slug>`, using descriptive
+  anchor text ("how agents hand off code", not "click here"). This is the single most
+  under-used lever here. It flows ranking between your posts and keeps readers on-site.
+  Reciprocate: when you ship a post, add one inbound link to it from the most related
+  existing post.
+- **One outbound link to an authority** (the MCP spec, a paper, a repo) signals the post is
+  situated in real work, not a content mill.
+- **Reading time and date** are already wired; keep them honest.
+
+## Verify the machine-readable SEO actually emitted
+
+On many blog systems the sitemap, RSS, per-post OpenGraph + Twitter cards, and `BlogPosting`
+JSON-LD auto-derive from the post's registry/frontmatter entry, so wiring the entry is most
+of the job. But verify it, do not assume. After your site's build command, serve the site
+locally and check:
+
+- The sitemap returns 200 and contains the new `<loc>` for the slug.
+- The RSS feed returns 200 and lists the new post.
+- View source on `/blog/<slug>` and confirm: `<meta name="description">` matches the
+  description, `og:title` / `og:image` / `twitter:card` are present, and the
+  `application/ld+json` `BlogPosting` block has the right headline, datePublished, author,
+  and keywords.
+- The cover image returns 200. A broken OG image kills the click-through on every social
+  share.
+
+If any of these is wrong, the SEO surface is broken even though the build was green. This
+step is not optional; it is the difference between a post that gets indexed well and one
+that gets a bad snippet.
+
+## Off-page: the distribution loop (this is what actually earns traction)
+
+A technically perfect post with zero inbound links does not rank. Google needs a signal
+that the page matters. You seed that signal yourself:
+
+1. **The X thread.** If `/x-tweet` is available in your environment, run it on the post's
+   core insight. The thread is not "new blog post link", it teaches the one sharp idea and
+   links the post as the deep-dive. One genuinely useful thread out-performs ten "check out
+   my article" posts. Link the exact post URL (`<your-site-url>/blog/<slug>`), not the
+   homepage.
+2. **The comment-where-the-question-lives play.** The post usually answers a real question
+   people ask (on Hacker News, the relevant subreddits, GitHub discussions, Lobsters). When
+   that question comes up, answer it for real and link the post as the fuller answer. Do not
+   drive-by drop links; that gets flagged and does the brand harm.
+3. **Cross-link from the repo.** Reference the post from the relevant docs and, when apt,
+   the README. Repo-to-post links are backlinks Google trusts and they route repo traffic to
+   the site.
+4. **Update, do not abandon.** When a post's facts change (a deferred feature ships, a
+   number moves), edit the post and bump nothing else. Fresh, accurate posts hold rank;
+   stale ones decay. Keeping the plain-markdown source makes this easy.
+
+## Going deeper on SEO fundamentals
+
+The rules above are the blog-specific subset. For the full SEO surface (structured-data
+schema choices, exhaustive OG/Twitter tag coverage, canonical and hreflang patterns, and
+Core Web Vitals), lean on the `astro-seo` skill, invocable as `/astro-seo` and published as
+`astro-seo-expert` at https://mcpmarket.com/tools/skills/astro-seo-expert. It is written for
+Astro, so ignore its Astro-specific integration code (`Astro.site`, `@astrojs/sitemap`,
+`@astrojs/rss`). What transfers cleanly and is worth pulling in:
+
+- **Structured-data recipes.** Which JSON-LD `@type` to emit and the required fields, beyond
+  the `BlogPosting` most blog systems emit (for example `BreadcrumbList`, `Person` author,
+  `Organization` publisher). Verify the values it recommends against what your build actually
+  emits (see the verify step above).
+- **Meta-tag completeness.** The full Open Graph and Twitter Card checklist to confirm every
+  card renders when the post is shared.
+- **Canonical and hreflang.** The canonical-URL discipline (point at the production host, one
+  canonical per page) maps onto whatever metadata layer your site uses.
+- **Core Web Vitals.** The LCP/CLS/INP guidance is framework-agnostic. A fast post page keeps
+  the bounce down and helps rank.
+
+Treat it as the reference textbook and `seo.md` as the house checklist: when they disagree on
+a blog-specific call (internal-link count, keyword placement), `seo.md` wins.
+
+## The public URL
+
+Outward links point at your canonical production domain, never a staging or preview host.
+Use the production domain in the thread, in cross-links, and anywhere a human will see it, so
+link equity accrues to the canonical host.

package/skills/write-blog/reference/voice.md

@@ -0,0 +1,64 @@
+# House voice + anti-AI checklist
+
+This is self-contained: you can enforce it even if the `/humanizer` command isn't loaded.
+But if `/humanizer` is available, run it too. This file is the house-specific layer on top
+of it.
+
+## What a good post sounds like
+
+- **Human and a little contrarian.** It has an opinion and defends it. It's willing to say
+  "most guides get this wrong" and then show why.
+- **Honest about what's deferred.** It names the limitations and the things not built yet.
+  That candor is the reason it doesn't read like a press release.
+- **Concrete, always.** Every claim is backed by real code from the project, a real command,
+  or a real number. Read the source before you describe it.
+- **Varied rhythm.** Short sentences next to long ones. Not every paragraph the same shape.
+- **First person when it fits.** "We shipped this and it broke in production" beats "the
+  system experienced an issue."
+
+## The hard rules (a post fails on any of these)
+
+1. **No em dashes (—) or en dashes (–).** Use a period, comma, "so", "because", or
+   parentheses instead. Run `check.sh` to catch strays.
+2. **No curly quotes.** Straight quotes only.
+3. **No emojis in body prose.**
+4. **Sentence case in headings, not Title Case.** "How agents hand off code", not "How
+   Agents Hand Off Code".
+
+## AI tells to strip (the checklist)
+
+Read the draft and remove each of these. This is the condensed version of the humanizer
+patterns, tuned for this blog.
+
+- **Significance inflation.** Cut "testament to", "pivotal", "groundbreaking", "in an
+  ever-evolving landscape", "plays a vital role", "underscores the importance". Say the
+  concrete thing instead.
+- **Promotional adjectives.** Cut "seamless", "powerful", "robust", "cutting-edge",
+  "revolutionary", "game-changing". Show the behavior; let the reader conclude it's good.
+- **Rule of three.** AI loves "fast, simple, and reliable" triples. Break the pattern. One
+  sharp adjective beats three padded ones.
+- **The -ing tail analyses.** Cut sentences ending in "...highlighting the need for...",
+  "...reflecting a broader shift...", "...underscoring how...". They add nothing.
+- **Negative parallelism.** Kill "it's not just X, it's Y" and "this isn't about X; it's
+  about Y". Overused to death by LLMs.
+- **Synonym cycling / elegant variation.** Don't call the same thing a "solution", then a
+  "platform", then an "offering", then a "framework" to avoid repetition. Repeat the plain
+  noun.
+- **Copula avoidance.** Prefer "is/are" over "serves as", "functions as", "stands as",
+  "acts as a".
+- **Vague attributions.** No "industry experts say", "many believe", "it is widely
+  regarded". Name the source or cut it.
+- **Hedging and filler.** "In order to" becomes "to". "Due to the fact that" becomes
+  "because". "At this point in time" becomes "now". "It is important to note that": just
+  say it. "Has the ability to" becomes "can".
+- **Generic positive conclusion.** No "in conclusion, as agents continue to evolve, the
+  possibilities are endless." End on something concrete.
+- **Sycophancy / chat artifacts.** No "Great question!", "I hope this helps", "Let me know
+  if...". This is an article, not a chat reply.
+- **Boldface overuse.** Bold a term once when introduced, not every noun.
+
+## The soul test
+
+After cleaning, read it out loud. If it sounds like a Wikipedia intro or a LinkedIn post,
+it's clean but soulless. Add back a real opinion, a specific war story, a dry aside. A post
+with a pulse converts; a tidy one bounces.

package/skills/write-blog/reference/wiring.md

@@ -0,0 +1,113 @@
+# Publish and wire the post into your site
+
+Blog systems differ (static site generators like Astro, Hugo, Eleventy, Next.js, or Jekyll;
+a CMS; or a plain markdown/frontmatter blog), but the wiring steps are the same everywhere.
+Do them in this order.
+
+## 1. Register the post in your site's index
+
+Add the post to whatever your blog uses to list published posts: a registry file, a content
+collection, a CMS entry, or the frontmatter that a content directory is scanned for. On many
+systems all SEO surfaces (sitemap, RSS, per-post OpenGraph + Twitter cards, and the
+`BlogPosting` JSON-LD) auto-derive from this metadata, so you do not wire them separately.
+Whatever the mechanism, the entry needs at least:
+
+- `slug` — kebab-case, matches the body file and the source markdown.
+- `title` — sentence case, no dashes.
+- `description` / standfirst — one to two sentences. This is your meta description, so
+  front-load the keyword phrase and make it read like a promise, not a summary.
+- `date` — ISO, drives the `<time>` element and sort order (and a human label if your system
+  wants one separately).
+- `readingTime` — honest.
+- `author`.
+- `tags` / keywords — these typically become the JSON-LD keywords.
+- `cover` — path to the cover image.
+
+## 2. Add the body in your blog's format
+
+Write the post body in whatever format your blog renders: a markdown/MDX file, a template, a
+component, or a CMS rich-text field. Whatever the format:
+
+- Give H2s an `id` so they can be deep-linked.
+- Use real links (not "click here"), and link to 1-2 related posts by `/blog/<slug>` for
+  internal SEO.
+- Quote real code from your project accurately.
+
+Copy the structure of an existing post rather than inventing a new layout.
+
+## 3. Make sure the SEO surfaces include the new post
+
+Confirm the sitemap, RSS feed, per-post OpenGraph + Twitter cards, and `BlogPosting` JSON-LD
+all pick up the new post. On systems where these auto-derive from the index entry (step 1),
+there's nothing extra to do but verify. On systems where they don't, add the post to each
+surface by hand. The page should fail loudly (a 404 / not-found) if the post is registered
+but its body is missing, or vice versa, so make sure both halves are present.
+
+## 4. Drop the prose source
+
+Keep the plain-markdown draft you wrote and humanized in your blog's source directory
+permanently. It's the source of truth for the prose; whatever your site renders is the
+rendered form. If your blog already authors directly in markdown, this and step 2 are the
+same file.
+
+## 5. Cover image
+
+Add the cover image where your site serves post assets. SVG or a raster image is fine. Match
+your site's brand palette. If you can't produce a good one, reuse an existing cover rather
+than shipping something ugly. A broken OG image kills the click-through on every social
+share.
+
+## Verify
+
+Your site's build command must be green. Then serve the site and smoke-test that these all
+load and include the new post: the post page `/blog/<slug>`, the cover image, the blog index
+(the new card shows), the sitemap, and the RSS feed. Re-run `bash check.sh` on the post's
+markdown source.
+
+## Example: Next.js
+
+As one concrete illustration, a Next.js site might wire a post like this (adapt to your own
+stack):
+
+- Register metadata by adding an entry to the top of a `POSTS` array in `web/lib/blog.ts`
+  (newest first). All SEO surfaces auto-derive from it.
+
+  ```ts
+  {
+    slug: "your-slug",
+    title: "Sentence case, no dashes",
+    dek: "One-to-two sentence standfirst that front-loads the keyword phrase.",
+    date: "2026-07-DD",
+    dateLabel: "July D, 2026",
+    readingTime: "N min read",
+    author: "Your Name",
+    tags: ["Primary keyword", "Secondary"],
+    cover: "/blog/your-slug.svg",
+  },
+  ```
+
+- Write the body as a React component in `web/components/blog/<slug>.tsx`, using shared prose
+  primitives (`ArticleH2`, `P`, `Lead`, `CodeBlock`, `A`, ...) from `components/blog/prose.tsx`
+  so every post renders identically.
+
+  ```tsx
+  import { Lead, P, ArticleH2, A, InlineCode, CodeBlock } from "./prose";
+
+  export function YourPostName() {
+    return (
+      <>
+        <Lead>The opening that names a concrete, specific problem.</Lead>
+        <ArticleH2 id="the-problem">The problem, plainly</ArticleH2>
+        <P>...</P>
+        <CodeBlock language="rust">{`// real code, quoted accurately`}</CodeBlock>
+      </>
+    );
+  }
+  ```
+
+- Register the body in `web/app/blog/[slug]/page.tsx`: import the component and add
+  `"your-slug": <YourPostName />,` to the `BODIES` map. The page falls back to `notFound()`
+  if either the `POSTS` entry or the `BODIES` line is missing.
+- Keep the prose source in `docs/blog/<slug>.md` and the cover in `web/public/blog/<slug>.svg`.
+- Verify with `npm run build` (must be green), then `next start` and confirm 200s for
+  `/blog/<slug>`, the cover, `/blog`, `/sitemap.xml`, and `/rss.xml`.