---

name: writer-blog description: Shopify blog article FORMAT rules — length, title, meta description, SEO, images. Read this ONLY when you are writing a Shopify blog article inside a task — task-content-publish's compose node or task-calendar-plan's generate node. It has no entry of its own and must never be entered directly. tags: [internal, marketing] license: MIT-0

Blog article rules (Shopify blog)

Governs FORMAT only. The brand voice comes from Brand IQ; product truth (only what the product tools returned) and the anti-AI-slop check (humanizer) belong to the task you are writing in — compose in task-content-publish or generate in task-calendar-plan — and you never need to read the other task to apply them. Publishing goes through task-content-publish's draft → review → publish flow with SHOPIFY_CREATE_ARTICLE.

Spec

field	rule
body	1200–1500 words by DEFAULT — a length the merchant named, or a subject that honestly supports less (a dates-and-facts announcement), overrides it. Never pad to reach the range: padding is the failure the voice rules below ban, not a spec met
title	≤70 chars; written for the piece's ACTUAL subject and angle, never bent around a keyword. The primary keyword joins the title only when it genuinely fits that angle — a keyword that does not fit stays out of the title and keeps its other placements (ruled 2026-10-22: with title placement mandatory, a store's Olympics keyword turned a waxing-at-home guide into "Snowboard Olympics 2026: …" — a title serving the keyword instead of the piece)
meta description	140–160 chars; one sentence that earns the click. Pass it as CREATE_CONTENT_DRAFT's seo_description argument — it becomes the article's search-engine <meta name="description">. NEVER write a "Meta description:" line (or the sentence itself) into the article body — the body is the visible post only.
structure	clear H2/H3 sections; short intro that states the payoff; skimmable
SEO	The article's SUBJECT is the featured products and the merchant's angle; the keywords frame how it is found and never turn it into an article about the keyword's own topic (an event term is a hook or one sentence of context, not the piece). Pick ONE primary keyword yourself: of the merchant's selected keywords, the one that names what this piece is actually about — its products or the merchant's angle — and matches its search intent; an event or trend term that only hooks onto them is never the primary, because the primary is placed four times and an event term gets one sentence (agency norm: one primary per article; in a batch SPREAD the selected keywords across pieces — batch_so_far shows what earlier pieces used, so rotate evenly rather than piling onto one. Fewer keywords than pieces means reuse is expected and fine: when a primary repeats, the piece's ANGLE must differ — same keyword, different article, never the same article twice). It must appear — natural variants count, verbatim not required — in the first paragraph, ONE H2, and the closing paragraph, and ride seo_description; it joins the TITLE only when it genuinely fits the piece's angle (title row above — never bend the title around it). When NONE of the selected keywords can honestly carry this piece (a card of misfit pre-filled defaults, or of event and trend terms only), the piece has NO primary keyword — seo_description takes the piece's own angle, and nothing in the copy is bent to manufacture one. The remaining selected keywords are SUPPORTING: the ones that fit become H2 subtopics; one that doesn't fit this piece is simply left out — never forced in; the card's keyword block still shows the merchant the full set, so nothing needs saying. Measured 2026-08-25: with only "weave naturally" here, four live articles used ZERO of the merchant's selected keywords — placement must be concrete or it doesn't happen
products	at most THREE per piece — the merchant's picker stops there and the draft tool refuses a fourth. More than three reads as a product feed and starves each one of copy; it also makes the model derive handles instead of copying them. Given more, pick the three that fit this piece's angle — the card's product block shows the merchant which made it
links	each featured product is CLICKABLE at its FIRST mention: the first time a product is named in the body, write that name as its product link; later mentions of the same product stay plain text — a paragraph where every repeat is a link reads as a catalogue. These mention links are navigation, not CTAs, so they do not touch the one-CTA rule: the piece still closes with exactly ONE call-to-action link — zero when the merchant asked for a piece that does not sell; their call outranks the count. A COLLECTION the piece naturally points to gets the same treatment: when one of the store's collections (SHOPIFY_GET_COLLECTIONS_SUMMARY) genuinely fits the piece — a gift guide, a seasonal line — weave ONE collection link into the body, the text [Browse the gift guide] followed immediately, with no space, by (collection: plus the collection's handle and ); no fitting collection means no collection link, never a forced one. Every product link / CTA is written as a HANDLE, never a URL — an ordinary markdown link whose target is product: plus the handle: the text [The Complete Snowboard] (or the CTA's [Shop the Complete Snowboard]) followed immediately, with no space, by the target (product:the-complete-snowboard). Copy the handle from the product's handle field, never derive it from its title. The server renders it into the real tracked URL when the draft is saved. A https:// link to this store, written by you, is never acceptable; neither is product_url or any other label standing in for an address. Third-party citations are ordinary URLs and stay that way. Full rule in the task you are writing in — compose in task-content-publish, generate in task-calendar-plan
images	cover image required — drawn WITH the draft from the hero_scene you pass to CREATE_CONTENT_DRAFT (see below); up to 3 in-body images placed with [[IMAGE: …]] markers where a section genuinely benefits — none when the merchant said no in-body images
discount code	When the piece carries a campaign, print THIS channel's variant code — {CODE}-BLOG, from the campaign's variant_codes map — never the campaign's main code. The article's links already carry UTM, but a reader who copies the code and buys days later is only attributable by the code itself. One code per article, in capitals Only ever print a code that came from a tool or the card — the campaign object names the codes that exist in Shopify. Never compose one, never adapt one you have seen, and if the piece carries no campaign then it carries no code: a code that does not exist is refused at checkout for every shopper who types it, and the draft tool refuses the piece rather than publishing it (measured on dev 2026-08-28 — an Instagram post advertised WINTERSALE10 on a store that has never had that code). Urgency is only ever the campaign's own. Say the offer ends on a date only when the campaign carries one — ends_at, or the end of the card's "Runs: X to Y" line — and quote that date as given — never a count of days left; a campaign with no end date gets no "limited time", "last chance", "ends soon" or "while it lasts"; and never say stock is running out. A deadline that is not real is a lie to the shopper, and a code that never expires next to "last chance" is exactly that.

Meta description — a field, not body text

Write a 140–160-char meta description and pass it as CREATE_CONTENT_DRAFT's seo_description argument — once, at draft time. It is stored with the piece and published from there, so you never pass it again at publish (it sets the article's <meta name="description"> for search engines). Do NOT append a "Meta description: …" line to the article body, and do NOT put the sentence anywhere in body_html — readers should never see it; it lives in the SEO field alone.

Image (required — drawn with the draft)

Every blog article ships WITH a cover image, and you do not draw it by hand: pass a hero_scene to CREATE_CONTENT_DRAFT — one clear English line of what the cover should SHOW — and the server draws it WITH the draft, grounding it in the featured products' real photos, attaching it to the card and, at publish, to SHOPIFY_CREATE_ARTICLE; the result answers hero_image: "drawn". Never call GENERATE_IMAGE for a hero, and never describe a cover the card does not have yet — illustrate exists only to CHANGE a picture the merchant already has, never to make a new piece's.

Nothing downstream needs an image address from you:

• CREATE_CONTENT_DRAFT: hero_scene is a DESCRIPTION, never an address. The cover is attached to the piece server-side, including a product photo when that is what the piece should show.
• SHOPIFY_CREATE_ARTICLE: leave the image arguments out. The cover comes from this piece's own reviewed draft, so what the merchant approved on the card is what publishes.
• To change the picture, call EDIT_IMAGE with just the change — no image argument, and no re-issued draft; the new picture reaches every card by itself.

In-body images — mark the spot, never the address

An article often reads better with a picture or two inside it. You put them there by marking the spot:

[[IMAGE: a snowboard base being waxed on a workshop bench, warm daylight]]

• Write the SCENE, in clear English, on its own line at a natural section break — what the picture should SHOW, the way you write a GENERATE_IMAGE prompt. The server draws it and puts it in the article for you.
• Never write an <img> tag, a markdown image, or a URL of any kind. You do not have the address and cannot get one. A marker is a description, so the worst a mistake can do is produce a picture nobody likes; a retyped address produces a broken image in a published article.
• Up to 3 markers, at section breaks, never two in a row — and only where a section genuinely benefits. Each one costs a generation, and an article that is more pictures than prose reads like a catalogue. A merchant who asked for no in-body images gets NONE: zero markers is a valid article. Anything past the third is dropped.
• The cover is not one of these. It is drawn with the draft from your hero_scene and attached to the card — do not mark a spot for it at the top.
• The scene is this SECTION's, not the article's. The picture sits next to the paragraph it follows, so describe what that paragraph is about; the server adds the article's title and the featured products' photos itself.
• If a picture cannot be drawn, its marker is simply removed and the article ships with fewer. Never mention the markers to the merchant.
• Rewriting an article that already has pictures: the markers are handed back to you — keep them. CREATE_CONTENT_DRAFT's result returns the body with each in-body picture as its own [[IMAGE: …]] marker again (it never returns an address). Send the body back with those markers in the same places and the same order and the article keeps exactly the pictures it had, undrawn and unchanged — the first marker gets the first picture, the second the second. Rewording a marker's scene does NOT order a new picture; you reword everything when you rewrite, and the merchant did not ask for new pictures. Drop a marker and you drop that picture.
• To actually replace one, say so: [[IMAGE new: <scene>]]. That one word is the whole difference. Use it only for the picture the merchant asked to change, and leave the others as ordinary markers. Never invent an address — the server checks every picture against the ones this piece really has and drops anything else.

Voice & structure

• Informative long-form: deliver real value, not padding to hit a word count.
• Front-load the answer, then support it — readers, search engines and AI assistants (ChatGPT, Perplexity, Gemini) all quote the passage that answers, so make that passage stand on its own. The first paragraph gives the piece's answer or payoff in two or three plain sentences (roughly 40–60 words) that still make sense lifted out of the article, and every H2 section opens the same way: its first sentence answers the heading — with the answer, never a restatement of the heading.
• Do: descriptive H2s a reader could skim as an outline, phrased — where the section answers one — as the question a shopper would actually type ("How often should you wax a snowboard?"); when the subject raises real buyer questions, a short FAQ before the closing CTA — three to five of those questions, each answered in its first sentence and complete on its own in 50–100 words — a real shopper question answered outright is not the staged question humanizer cuts, but a question nobody would ask is; state the product facts a shopper compares — material, size, fit, compatibility, care — in plain sentences with their units, only as the product tools returned them (price keeps its own rule below); close with a real-link CTA. These are how the article is organised for its readers, not a second version for machines: never chop it into fragments, and never add a section the piece does not need.
• Don't: thin filler, repeated keyword phrases, generic intros ("In today's world…"), invented product links, a vague claim where a fact belongs ("premium quality" instead of what the board is made of).
• Price appears ONLY when it is the message — an attached campaign's discount anchor, or the merchant's brief names affordability as the selling point. Otherwise leave it out: an article outlives any price tag, the linked product page owns the current number, and published copy cannot be re-priced — a stale price in an evergreen post is misinformation with the merchant's name on it.