Blog Writer

You are coordinating a small swarm to ship one production-quality long-form blog post for vibestack's marketing journal. The output lands as a draft MDX file in apps/marketing/content/blog/, ready for human review.

Each post: 15-20 minute read = 3500-5000 words, with 4-8 inline images placed at natural reading breakpoints (not just a cover), full SEO metadata, internal links to vibestack surfaces where natural, and copy that earns the reader's time without being a thinly-veiled product ad.

Phase 0 — Brief

Ask the user at most two clarifying questions in one round, only if their request is ambiguous. Otherwise proceed silently from a sensible inference.

Required inputs you must resolve before launching the swarm:

• Topic — short title or theme. May be product-adjacent ("deploying with Dokploy", "Better Auth passkeys") or pure domain content ("Postgres connection pooling in 2026", "what AI-search engines reward in 2026"). The latter is encouraged — it builds topical authority without sounding like an ad.
• Audience lane — developer (eng on Hacker News / Reddit / Lobsters; technical depth, code snippets, opinionated takes) or founder (indie hackers / vibe-coders; concrete decisions, money implications, no jargon walls) or mixed.
• Angle (optional) — the take. If the user said "write about X", invent the angle and surface it in your one-question round: "Going to angle this as 'X: the underrated reason it's faster than Y'. OK or counter?"

If the user just types /blog-writer with no args, ask:

> "Topic, audience (developer / founder / mixed), and any specific angle you want? I'll pick a default angle if you skip it."

After one round, infer the rest and proceed.

Phase 1 — Spawn the swarm

There are five worker agents, run in three stages (not all parallel). Each agent's prompt is self-contained; they cannot see this session.

Researcher  →  Writer  →  ( SEO Editor  +  Image Prompt Architect )  →  Image Producer  →  Publisher
   solo        solo              parallel pair                            solo            you

Stage 1 (solo): Researcher. Stage 2 (solo): Writer. Stage 3 (parallel pair, one Task message with two Agent calls): SEO Editor + Image Prompt Architect. Stage 4 (solo): Image Producer. Stage 5: Publisher (you, summarising to the user).

Why the Image Prompt Architect runs as its own agent. Gemini image output goes generic when the prompt is generic. The Researcher's image marks are placeholders to anchor where images go, not what they should look like. Real visual hooks emerge only after the Writer has drafted the surrounding paragraphs. The Prompt Architect reads the actual section text and writes a tight, concept-specific prompt before Image Producer ever calls Gemini. Skipping this step is the dominant cause of "abstract gold cubes / circles / triangles" output.

Agent A — Researcher

Owns: keyword research, competitor outline scan, internal link inventory, citation set, structured brief.

Prompt template:

> Working dir: /home/smilox/git/side/starter-saas. Write a research brief for a long-form vibestack blog post. Topic: "{TOPIC}". Audience: {AUDIENCE}. Angle: {ANGLE}. > > Your job, in order: > 1. Keyword work. If the toprank plugin is installed (test by checking whether /toprank:keyword-research is in the available skills list), invoke it for the topic and capture: primary keyword, 5-8 secondary keywords, search volume + difficulty if returned, and the questions People-Also-Ask surfaces. If toprank is not available, fall back to WebSearch — query the topic, scan 5 top-ranking results, extract the H2 structure of each, and infer keyword + secondaries from title overlap. > 2. Competitor outline scan. WebSearch for "{TOPIC}" and read the top 3 results. Note: H2 structure, word count estimate, what they got right, what they missed. Identify a gap you can fill. > 3. Internal link inventory. Scan apps/marketing/content/docs/ and apps/marketing/content/blog/ for posts/pages that this article could link to. Output exact /docs/... or /blog/... URLs from .url frontmatter where possible. > 4. Cite-worthy sources. 5-8 external URLs the writer can cite. Real, working URLs. Skip anything older than 2024 unless it's canonical (Postgres docs, RFCs, etc.). No Wikipedia. > 5. Outline. 6-9 H2 sections (each H2 ≈ 400-700 words in the final piece). For each: one-sentence intent + 2-3 H3 sub-bullets. The piece must total 3500-5000 words. Build the outline to that budget. > 6. Image-break points. Mark which H2 boundaries call for an inline image, and what each image should depict (≥ 4, ≤ 8 marks total, including the cover). Each image mark gets a one-sentence prompt for Gemini (e.g. "Editorial illustration: minimal abstract diagram of three Postgres connections converging, gold accent, dark blue-black background, no text"). Style language must match the marketing brand — see DESIGN.md at the repo root. > > Output a single JSON object printed to stdout, schema: > ``json > { > "topic": "...", "angle": "...", "audience": "...", > "primaryKeyword": "...", "secondaryKeywords": ["..."], > "competitors": [{"url": "...", "gap": "..."}], > "internalLinks": [{"url": "/docs/...", "label": "..."}], > "citations": [{"url": "...", "label": "..."}], > "wordTarget": 4200, > "outline": [ > {"heading": "Why X matters in 2026", "intent": "frame the problem", "subBullets": ["...", "..."]} > ], > "imageMarks": [ > {"after": "Why X matters in 2026", "geminiPrompt": "Editorial...", "alt": "Abstract..."} > ] > } > `` > > Report back under 200 words plus the JSON.

Agent B — Writer

Owns: drafting the 3500-5000 word MDX body from the researcher's brief. Image placeholders only — no real images yet.

Prompt template:

> Working dir: /home/smilox/git/side/starter-saas. Draft the long-form blog post body for vibestack. > > Inputs (from researcher): > ``json > {RESEARCH_JSON} > ` > > Constraints: > - **Length: 3500-5000 words**, distributed across the researcher's outline. Don't pad — if a section is genuinely 400 words, leave it. > - **Voice**: confident, specific, technical-but-readable. Concrete examples beat platitudes. No filler ("In today's world", "It is important to note"). Conversational where it earns its place, formal where precision matters. > - **Style rules**: no em dashes (use commas, colons, periods, parens). No gradient-text language. No "AI slop" phrases ("delve", "in the realm of", "leverage", "harness the power of", "unlock", "tapestry"). No empty intros — the first paragraph must do real work. > - **Structure**: > - 2-3 sentence opening hook. State the angle. > - ## TL;DR section: 3-5 bullets. Don't title it anything cute. > - All H2s from the researcher's outline, in order. Use ### H3 sub-sections inside an H2 only when there's real sub-structure. > - Internal links to the researcher's internalLinks array, woven naturally. At least 3. Markdown links: [label](/docs/...). > - External citations from the researcher's citations array, attributed in prose ("per the Postgres docs", "Zuckerberg's [2025 letter](...)"). At least 4. > - A ## FAQ section with exactly 5 question/answer pairs. Bold the Qs. > - A ## Closing section: one paragraph, one call to action that's relevant (often /sign-up for vibestack, but feel free to link /docs/ if the user is mid-task). > - Code fences for any snippet. Specify the language. > - **Image placeholders.** At each imageMark.after boundary in the researcher's brief, drop a literal HTML comment in this exact shape: . Use literal "PLACEHOLDER" for both fields, OR a one-line stub describing the section topic. The Image Prompt Architect (Agent C1) rewrites these later with section-anchored prompts; don't waste tokens crafting them now. The position matters, the content does not yet. > - **Frontmatter.** Build the frontmatter at the top. Fields: title (one line, ≤ 60 chars, includes primary keyword naturally), description (≤ 155 chars meta-description-shaped, includes primary keyword), date (today, YYYY-MM-DD), keywords (array: primary + 3-5 secondaries), author ("vibestack"), readingTime (estimated minutes, integer), draft: true, aiGenerated: true, aiReviewedBy: pending, tags (2-4 short kebab-case strings). > > Use the Write tool to write the final MDX to apps/marketing/content/blog/{YYYY-MM-DD}-{slug}.mdx. Slug = kebab-case of the primary keyword (max 64 chars). > > Report the file path, word count (run wc -w` on the body, not frontmatter), and how many image placeholders you embedded. Under 150 words.

Agent C1 — Image Prompt Architect (NEW; runs in parallel with C2)

Owns: rewriting every ` placeholder's prompt and alt` so each image is anchored to the actual section content it sits inside. The Writer's placeholders are intentionally generic; this agent makes them specific.

Prompt template:

> Working dir: /home/smilox/git/side/starter-saas. Rewrite the inline image prompts in {DRAFT_FILE_PATH}. Read the file, find every ` block, then for each one: > > 1. **Locate the surrounding section.** Look at the nearest ## H2 heading above the placeholder (or the nearest ### H3 if no H2 is closer) and the 1-3 paragraphs immediately surrounding the placeholder. > 2. **Identify the section's load-bearing idea.** What specific concept, tension, or claim does this section make? "AI coding agents replace boilerplate" is a load-bearing claim; "tools are evolving" is not. If the section is a list of items, pick the one item that most needs visualising. > 3. **Pick a visual concept** for that idea. Concrete > abstract. **Avoid the default reflex of "abstract gold shape on dark background".** Push for: > - A concrete metaphor: e.g. for a section on race conditions, "two hands reaching for the same chess piece, frozen at the instant of contact"; for connection pooling, "a single drinking-fountain tap with five identical paper cups stacked beneath it"; for type narrowing, "a wide funnel narrowing to a single drop". > - A stylised object or still life: a battered Moleskine open to a diagram page, a pile of unopened mail with one envelope on top, an oscilloscope screen frozen on a single waveform. > - A scene with one human-scale element: a single chair in a server room, an empty whiteboard with three magnets, a porthole window onto a starlit ocean. > 4. **Pick a visual style per image** — vary across the post so the body doesn't read as one repeated illustration. Rotate between (pick one per image, do not repeat the same style twice in a row): > - "Editorial photograph, single-light still life, shallow depth of field" > - "Isometric vector illustration, 3D-perspective, thin line work" > - "Minimalist flat illustration, mid-century editorial poster style" > - "Cinematic frame still, wide-angle, soft directional rim-light" > - "Architectural diagram in the style of a hand-drawn 1970s technical manual" > - "Macro photograph of a single object on a textured surface" > 5. **Brand constraints** (apply to every prompt verbatim, at the end): > - Background: deep blue-black, never pure black. Reference colour: oklch(0.13 0.012 250). > - One warm-gold accent appears somewhere in the frame. Reference colour: oklch(0.84 0.13 88). > - No text, no logos, no UI mockups, no charts, no graphs with axes, no Lorem Ipsum. > - No human faces in close-up. Hands, silhouettes, partial figures are fine. > - Aspect ratio: roughly 2:1 horizontal. > 6. **Alt text**: write a literal, screen-reader-quality description of the rewritten visual. Not a paraphrase of the section. 8-16 words. > > Each rewritten prompt should be **3-5 sentences**, not a single noun phrase. Lead with the concept, then the style, then the brand constraints. Example shape: > ` > Two open hands stretched toward each other, palms up, the last grain of sand falling between them onto a stone floor. Editorial photograph, single-light still life with deep shadow, shallow depth of field. The grain catches a warm-gold highlight, the only saturated colour in the frame. Deep blue-black ambient background, no text, no logos. 2:1 horizontal frame. > ` > > Use the Edit tool to replace each placeholder block in place. Preserve the delimiters and the JSON structure (just change the prompt and alt values). Do **NOT** rewrite or move any other content. Do **NOT** generate images here — only rewrite text. > > Important coordination: Agent C2 (SEO Editor) is editing the same file in parallel on different concerns (meta, headings, internal links, keyword density). It edits text outside the image placeholder blocks. Limit your edits to the JSON inside ` blocks. If you collide on the file, retry the affected Edit; the placeholder structure makes the diff trivially mergeable. > > Report under 200 words: how many placeholders you rewrote, one example before/after, and the section heading each rewrite anchored to.

Agent C2 — SEO Editor

Owns: pass over the writer's draft. Tighten meta, fix H1/H2 hierarchy, add alt text to image placeholders, verify internal links resolve, check schema readiness.

Prompt template:

> Working dir: /home/smilox/git/side/starter-saas. SEO editing pass on the draft at {DRAFT_FILE_PATH}. Read it, then: > > 1. Meta sanity: title 50-60 chars, description 140-160 chars. Both include the primary keyword. If the writer overshot, trim. Don't change the angle. > 2. Heading hierarchy: exactly one H1 (the title) — but MDX uses frontmatter for that, so the body should NOT contain an # H1. All body headings are H2 minimum. Verify and fix. > 3. Keyword density: primary keyword appears in title, description, first 100 words, and in 2-4 H2s. Not stuffed — read naturally. Adjust if obvious gaps. Avoid stuffing. > 4. Internal links: verify every [label](/foo) resolves to a real path under apps/marketing/content/ or a top-level marketing route (/, /blog, /docs, /changelog, /roadmap, /status, /sign-up, /sign-in). Replace broken ones with the closest real URL or remove with a brief note in your report. > 5. External link rel: all https?:// URLs in markdown links are fine as-is (MDX renderer handles rel=noopener for external links if the Link component supports it, otherwise it's a follow-up). Don't rewrite, just count. > 6. Image placeholders: every ` block must have a non-empty alt. If any are missing, infer alt from the surrounding paragraph. > 7. **FAQ schema-readiness**: the ## FAQ section format must be exactly Q. ... paragraphs followed by an A paragraph — fumadocs converts those to FAQPage JSON-LD downstream. > 8. **Reading time**: re-count words (wc -w excluding frontmatter), recompute reading time at ~230 wpm, update the readingTime frontmatter field. > > Edit the file in place using Edit`. Don't rewrite the whole thing. Don't change voice or argument. > > Report the changes you made as a short bulleted list, plus the final word count and reading time. Under 200 words.

Agent D — Image Producer (runs AFTER C1 + C2 both return)

Owns: walk the draft (with prompts now rewritten by C1), generate each inline image via Gemini, replace placeholders with `` HTML.

Prompt template:

> Working dir: /home/smilox/git/side/starter-saas. Generate inline images for {DRAFT_FILE_PATH}. > > Pipeline: > 1. Read the file. Find every ` block. > 2. For each placeholder, in order: derive an output filename from the post's slug + image index, e.g. apps/marketing/content/blog/{slug}/images/01-{kebab-slugified-alt}.png. > 3. Run pnpm exec tsx scripts/gen-image.ts --prompt "..." --out "..." --size 1536x768 --max-kb 320 for each. The script exits 78 if GOOGLEAIAPI_KEY` is missing — if that happens, stop processing immediately and report the gap. Don't fake images. > 4. Replace the placeholder comment in th

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: f-amine
• Source: f-amine/vibe-stack
• License: MIT
• Homepage: https://vibestack.salzier.com

Install and usage instructions live in the source repository linked above.