1---2name: article-write3description: >-4 Writes a B2B SaaS article from a finished research brief: outline, draft in the company's voice, citations,5 internal links, title, meta description and JSON-LD, then checks its own work in layers (a QA pass, a script for6 everything countable, voice-check, claim-check and one reviewer with fresh eyes), fixes what failed in at most 27 rounds, and stops for the reader's signoff with every open item labelled. Use it after article-research returns8 READY or READY WITH GAPS. Not for choosing or researching a topic (use topic-precheck and article-research) or for9 short posts (use founder-post or repurpose).10license: MIT11compatibility: >-12 Works in Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md. Opens sources and the site's pages if the13 agent can browse; otherwise works from the research brief and pasted pages. Python 3 is optional, for the14 mechanical checks. A subagent or second chat is optional, for the fresh-eyes review.15metadata:16 author: SHAKEUP17 version: "1.0.0"18 stage: make19 plugin: content20 homepage: https://www.shakeuphq.com/skills/article-write21---22 23# Article write24 25Turns a research brief into a finished, checked article, so the reader's signoff is about judgment, not typos, broken links or unsourced figures.26 27## Purpose28 29- One job: one article, with its metadata, schema and notes, ready for the reader's signoff.30- Stage: make. It ends in its own layered check and a fix loop of at most 2 rounds.31- It never publishes, never invents a figure, quote, customer, experience, author or credential, and never ships a sentence whose claim failed a check: it cuts the sentence and logs the gap.32 33## Use when / not34 35| Situation | Use |36| --- | --- |37| `article-research` returned READY or READY WITH GAPS | this skill |38| Rewriting an article from a fresh brief | this skill |39| No research yet | `article-research` (and `topic-precheck` before it) |40| Checking a draft someone else wrote | `voice-check`, `claim-check`, `eeat-check` |41| Editing a live page from an audit | `refresh-audit` for the edit list, then this skill for the sections it touches |42| Posts, emails or scripts from the finished article | `repurpose` |43 44## Inputs45 46| Input | Required | Ways to provide, in order | If missing |47| --- | --- | --- | --- |48| The research brief | yes | an `article-research` handoff and brief; a brief the reader pastes | `BLOCKED`: ask for it, or run `article-research` |49| A named author with a bio page | yes | the precheck or research handoff; `## Content` > `Authors` | `BLOCKED`: never invent a byline |50| The pillar and link targets | no | the precheck and `cluster-fit` handoffs; the sitemap if browsing; pages the reader lists | links from the brief only; flag "internal links not checked" |51| Voice rules | no | `## Voice` in the profile | write plain and direct; coverage `partial` |52| Approved claims | no | `## Claims and proof` | no first-party figures at all |53| Product mention rules | no | the reader's request; `## Product`, `## Positioning` | no product mentions |54 55## Profile read56 57From `company-profile.md`: `## Company` (website, brand terms), `## Product`, `## Buyers`, `## Buying moments`, `## Positioning`, `## Messaging house`, `## Voice`, `## Claims and proof` (with `### Never say`), `## Competitors` (mention policy), `## Content` (authors, site sections), and every `## Learnings` entry for `article-write`, `voice-check` and `claim-check`.58 59No profile: ask in one message for the website, the author's name and bio link, 3 to 5 words for the voice, and any figures the company can publish with their sources. Say that `company-profile` saves this next time.60 61## Steps62 631. **Apply learnings.** Accepted rules override the defaults (for example "no definition box on our blog", "never mention pricing").64 652. **Gate the brief.** `COMMODITY`, `BLOCKED` or no brief means `BLOCKED`. Carry forward: primary keyword, angle and its evidence, verified sources, suggested sections, pillar, author, YMYL flag, and every gap. A gap stays a gap in the draft.66 673. **Outline.** Apply `references/writing-rules.md` section 1: fix the parameters, then the H2 structure (active intent first), formats, key points, E-E-A-T and citation flags, FAQ, product mention points and link positions. The outline goes in the output for the reader; it is not a stop.68 694. **Draft.** Apply section 2 in the profile's voice: title, introduction (tension in the first 2 sentences), key takeaways, the sections, definition box and pull quote where they earn a place, FAQ, close. Every figure from the brief's verified list or `## Claims and proof`. Experience lines only where the brief or the author backs them.70 715. **Citations.** Apply `references/citations-and-links.md`: each external claim linked once at its sentence, publisher named, no links in headings or the introduction. A figure without a verified source is cut or reframed, and logged.72 736. **Internal links.** Same file: live pages only, type caps, placement after the first 10%, anchors of 2 to 6 words that name the target's topic. The pillar link is required for supporting content. List up to 5 pages that should link here after publishing.74 757. **Metadata and schema.** Apply `references/meta-and-schema.md`: title tag and meta description (a primary and 1 alternative each), slug, JSON-LD that matches the visible page, and the schema recommendations note.76 778. **QA pass.** Score the draft against `references/review-rubric.md`, plus these people-first checks: it says something the top results don't (the angle is stated); every figure traces to a source opened in this run; a real author is named; the modified date changes only with real changes; nothing is written for AI crawlers instead of readers; the title, description, schema and alt text hold up as well as the body. Fix every critical.78 799. **Mechanical checks.** Run:80 81 ```82 python3 scripts/article_checks.py --article article.md --profile company-profile.md \83 --domain <site domain> --require-link <pillar URL> --require-schema84 ```85 86 Without Python, check by reading, in this order: dashes; words to avoid; leftover markers (`[[...]]`, comments, TODO, `[CITATION NEEDED]`, `[blank]`); H1 count; link targets and weak anchors; the required pillar link; internal links against 2 per 1,000 words; paragraphs over 75 words; title 30 to 60 and description 70 to 160 characters; takeaways 3 to 5; FAQ 5 to 7 with answers of 3 sentences or fewer; JSON-LD that parses, has `@type` and matches the visible FAQ. Say which way you ran it.87 8810. **Voice and claims.** Run `voice-check`, then `claim-check`, on the draft and the metadata. Without them installed, apply inline: the profile's words to avoid, point of view, sentences over 30 words, and the 3 copy tests; then every figure and comparison against `## Claims and proof` or its verified source, every `### Never say` line, and the competitor mention policy.89 9011. **One reviewer with fresh eyes.** Give a separate subagent (or a new chat) only the draft, the research brief and `references/review-rubric.md`. It quotes the exact text for every finding. Without a subagent, reread cold from the brief and say the review was not independent. Items only a person can judge are marked `needs the author`.91 9212. **Fix and recheck** (the Loop below), then stop for signoff.93 94## Check and verdict95 96Severity comes from each layer: `blocker` (script), `critical` (QA, voice-check, claim-check, reviewer), `warning`, `suggestion`.97 98| Verdict | Condition (first match wins) |99| --- | --- |100| `BLOCKED` | No research brief; the brief is `COMMODITY`; no named author; or the reader asks to invent a byline, credential, quote, customer or result |101| `SIGNOFF WITH OPEN ITEMS` | After the loop: 0 blockers and 0 critical in the draft, but warnings remain, or open items need input (a gap from research, a quote waiting for clearance, YMYL expert review, `needs the author` items) |102| `READY FOR SIGNOFF` | 0 blockers, 0 critical, no warnings left that have a clear fix, voice-check and claim-check PASS or PASS WITH NOTES, reviewer pass or pass with notes, no open items needing input |103 104A draft never reaches signoff with a critical in it: when a fix would need an invented fact, cut the sentence and log the gap instead.105 106Named stops: `BLOCKED` asks for the missing input. Signoff: every run ends by stopping for the reader to approve, with the article, the open items and the check results. Nothing in between stops.107 108## Loop109 1101. Collect every blocker, critical and warning from steps 8 to 11 into one list, each with its line and source layer.1112. Fix in order: blockers, criticals, then warnings with a clear fix. A fix changes only what failed; never add a claim to fix a finding.1123. Rerun the script, `voice-check` and `claim-check` on the changed draft. Rerun the reviewer only if round 1 changed a section's argument.1134. At most 2 rounds. Then hand over: anything still open is labelled `open` with its layer, line and what would close it.114 115When the script and the reviewer disagree about something countable (a paragraph's length), trust the script.116 117## Learn118 119Append to `## Learnings` when:120 121- the reader rejects a reviewer finding or reverses a fix at signoff (a `proposal`, with their reason: "we do use 'platform' as our category term");122- the reader makes the same edit at signoff twice (a `proposal` to make it a rule, such as "no pull quote");123- the article's results come back, such as impressions, rankings, demos or citations after 90 days (a `fact`, with its source).124 125Example: `- 2026-10-24 | article-write | proposal | Put the comparison table in the first H2 for compare-intent articles | Why: the reader moved it up in 2 of the last 3 signoffs | Status: proposed`126 127## Output128 129```130Verdict: <READY FOR SIGNOFF | SIGNOFF WITH OPEN ITEMS | BLOCKED> · Coverage: <complete | partial (what's missing)> · Rounds: <0 | 1 | 2>131 132Outline: <parameters, then one line per H2: heading, job, format>133 134<article.md: front matter (title, description, slug, author), the article body, the JSON-LD block, then SCHEMA RECOMMENDATIONS>135 136Checks137| Layer | Result | Open |138| QA pass | <pass | pass with notes | fail> | <n> |139| Mechanical (<script | by reading>) | <pass | fail> | <blockers, warnings> |140| voice-check | <verdict> | <n> |141| claim-check | <verdict> | <n> |142| Reviewer (<independent | not independent>) | <pass | pass with notes | fail> | <n> |143 144Notes (open items): <each with its layer, the line and what would close it>145Links to add from other pages: <page → concept>146Learnings applied: <list, or none>147```148 149Then the handoff block. Then stop for signoff.150 151## Hand off152 153```handoff154skill: article-write155version: 1.0.0156verdict: SIGNOFF WITH OPEN ITEMS157coverage: complete158for: <article title>159outputs:160 title: <H1>161 slug: <slug>162 primary_keyword: <keyword>163 author: <name>164 pull_quote: <the pull quote line>165 verified_sources: [<url>, <url>]166 checks: {blockers: 0, critical: 0, warnings: 2}167next: [eeat-check, repurpose]168open: [customer quote on <subtopic> waiting for clearance]169```170 171`repurpose` reads `pull_quote` and `verified_sources`; `eeat-check` reads the draft and `author`.172 173## Failure modes174 175| Problem | Do this |176| --- | --- |177| A verified source can't be reopened at write time | Keep the claim only if the brief recorded its excerpt; otherwise cut it and log it |178| The vague rewording of an unverified claim would still imply it | Drop the sentence entirely |179| The reader wants word counts | Explain that length follows from covering the key points; give the current length as information only |180| The profile allows no product mentions but the reader asks for a call to action | One conversion link in the final 20%, no product claims |181| The topic is YMYL | Mark the draft for expert review at the top of the notes, source every factual claim, state limits plainly; the verdict is at best `SIGNOFF WITH OPEN ITEMS` until the review is done |182| No subagent and no second chat | Run the reviewer pass cold from the brief and say it was not independent |183 184## Influenced by185 186- Google's guidance on helpful, reliable, people-first content and on using generative AI in content creation, which put accuracy, a real author and original value ahead of how the content was made: https://developers.google.com/search/docs/fundamentals/creating-helpful-content and https://developers.google.com/search/docs/fundamentals/using-gen-ai-content187- SHAKEUP's content engine: every countable check done by a script before a reviewer reads the draft, one reviewer with fresh context who must quote the text, gaps logged instead of filled, and signoff always left to a person.