Newsletter SEO Pipeline#

Article Header Block (required in every output file)#

Every article must start with this block — scripts depend on it:

text

Meta Title: <50–60 chars, includes primary keyword>
Meta Description: <150–160 chars, includes keyword + value prop>
URL Slug: <keyword-rich-hyphenated-slug>
Primary Keyword: <exact keyword phrase>

Production Workflow (run in order — do not skip steps)#

Step 1 — SERP Analysis#

Run serp-analysis skill on the primary keyword. Goal: identify content gaps, SERP features, search intent, and top-ranking structure.

Step 2 — SEO Outline#

Run seo-content-engine skill. Goal: keyword variants, H2/H3 structure, target word count, internal link opportunities.

Step 3 — Write#

Run article-writing skill using the outline from Step 2. Include the Article Header Block at the top of the output file.

Voice reference: projects/<slug>/writing-style.md — where <slug> is the project slug from the project memory file. This file lives in the newsletter's project folder and was generated during newsletter-launch setup.

If missing:

• Check the project folder at projects/<slug>/ — it should be there
• If the whole project folder is missing, re-run newsletter-launch for this newsletter
• If only writing-style.md is missing, recreate it by running newsletter-launch and choosing 'update style guide' when prompted

Step 4 — AI Pattern Pre-Screen#

The skill directory = the folder containing this SKILL.md file. Use its absolute path throughout. Run the pre-screen script:

text

python3 <skill_dir>/scripts/score_ai_patterns.py <article_file>

• Score ≥ 8: proceed to Step 5
• Score < 8 and de-ai-ify skill is installed: run it, then re-run the script to confirm ≥ 8
• Score < 8 and de-ai-ify is NOT installed: manually rewrite flagged patterns (script lists them by line), then re-run the script until score ≥ 8 before continuing

Step 5 — Quality Gate (built-in QVP)#

Check all 5 gates. Each must pass before continuing:

1. Completeness — does the article fully address the target keyword and search intent? No gaps, no unanswered questions a reader would have.
2. Accuracy — are all facts, stats, dollar figures, and claims verifiable? No fabricated sources. Flag any uncertain claims explicitly.
3. Source integrity — every stat or claim must trace to a real, named source (publication, study, company report). No "experts say" or vague attributions.
4. Action clarity — every H2 section must end with a clear action the reader can take. No insight without a takeaway. Ownership must be clear.
5. Format check — Article Header Block is present and complete. Meta title 50–60 chars. Meta description 150–160 chars. Exactly one H1. At least 3 H2s. No placeholder text remaining.

If any gate fails: fix the specific issue, then re-check that gate before continuing. Do not proceed with a failed gate.

Step 6 — SEO Validation#

Run the validator script. Resolve path relative to this skill's directory:

text

python3 <skill_dir>/scripts/validate_seo.py <article_file> "<primary keyword>"

Fix all ❌ ISSUES before continuing. ⚠️ WARNINGS should be fixed but are not blocking.

Step 7 — Markdown Format#

Run markdown-formatter skill for a final clean formatting pass.

Step 8 — Build Paste Doc#

Generate the beehiiv-ready publish doc. Resolve path relative to this skill's directory:

text

python3 <skill_dir>/scripts/build_paste_doc.py <article_file> <YYYY-MM-DD>

This produces <article_file_stem>-PASTE.md — the file the user copies into beehiiv.

Output#

Alert the user with:

• Path to the final article file
• Path to the -PASTE.md file
• Confirm all gates passed: QVP ✅, SEO validation ✅, AI score ✅
• Include the AI score (e.g. 9/10), so the user knows the quality level

Context Required#

Before running the pipeline, the calling context (cron, user message, or issue template) must supply:

• Project slug — to locate projects/<slug>/writing-style.md and output files to the correct folder
• Primary keyword — for SERP analysis and SEO validation
• Publish date — for the paste doc (YYYY-MM-DD)

These are always present in the cron payloads generated by newsletter-launch. If running manually, read the project memory file at projects/<slug>/project.md first.