Newsletter SEO Pipeline

Article Header Block (required in every output file)

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

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//writing-style.md — where 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// — 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:

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:

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:

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

This produces -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//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//project.md first.