# SEO Blog Writer > Fully automated SEO article writer. Give it a topic and domain — it handles everything: auto-discovers product context, researches keywords, analyzes competitors, writes the article, verifies links, and delivers a complete publication package (article + QA report + schema markup + promotion checklist). One confirmation gate before writing starts, then hands-off execution. Works for any site, any industry, any CMS. No hardcoded dependencies. - Skill: `lord1egypt/seo-blog-writer` (Agent Skill) - Install (CLI): `npx skillmds@latest add lord1egypt/seo-blog-writer` - Raw SKILL.md: https://api.skillmd.com/api/skills/lord1egypt/seo-blog-writer/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: Lord1Egypt (https://skillmd.com/u/lord1egypt) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/lord1egypt/seo-blog-writer --- # AI-Driven SEO Blog Writer > **Long-running task mode.** This skill generates a multi-phase artifact. Before Phase 0: create a `task-logs/{slug}/` workspace, write each phase output to disk incrementally, and use offset reads to verify writes. This ensures crash-safe, resumable execution without regenerating completed work. ## Design Principles **Minimum viable input** - topic + domain is all you need to start **Verify before assert** - no statistic, quote, or claim goes in unverified **One checkpoint** - you confirm the plan before a single word is written **Zero dependency** - no local project files, no paid tools required **Honest degradation** - when automation fails, the skill says so clearly and gives you the next step --- ## Execution Model (IMPORTANT) This is a heavy, multi-phase skill. Incremental disk writes and offset-read verification are mandatory — see the long-running task note above. **When spawning as a subagent, file writes and link verification (Phases 1–5) require exec permissions:** ``` sessions_spawn( task: "SEO article: topic='[topic]' domain='[domain]' mode='[mode]'", runtime: "subagent", security: "full" ← needed for disk writes and curl-based link checks ) ``` If running in the main session directly, exec permissions are already present — proceed normally. > **Why `security: "full"`?** This skill writes article drafts, QA reports, and schema files to disk incrementally (crash-safe execution). Link verification uses `curl`/`web_fetch` to check URLs. Both operations require exec access. If you prefer not to grant this, run the skill in your main session rather than as a subagent — behavior is identical. --- ## Failure Recovery Guardrails (Mandatory) For this skill, "done in one shot" is not trusted. Use bounded, resumable execution: 1. **Section-by-section writes** - Write article sections incrementally (intro, each H2 block, FAQ, conclusion). - After each section write, append checkpoint to `task-logs/{slug}/report.md` (or your preferred output dir). 2. **Write-then-read verification** - After every `write`/`edit`, run a targeted read/grep to confirm the change exists. - Do not queue multiple blind edits without read-back. 3. **Timeout-safe continuation** - If model timeout / prompt-error / length stop occurs: - persist current section to disk immediately - continue from next missing section - do not regenerate completed sections unless explicitly requested. 4. **QA loop cap** - Max 3 QA rounds. - Each round fixes only concrete FAIL items from latest report. - If a FAIL item is stale (already fixed), verify by grep/read and mark as stale report issue. 5. **SERP analyzer degradation** - If QA says "SERP analyzer unavailable", treat as warning. - Continue with link/citation/structure fixes; do not block publication solely on SERP fetch failure. --- ## Quick Start ```yaml # Minimum input topic: "best AI email apps 2026" | "gmail alternatives" | "how to manage email overload" domain: "https://yoursite.com" # Optional mode: "express" | "standard" | "expert" # default: standard product_context: "path/to/context.md" # skip auto-discovery if you have this output_dir: "." # default: ./seo-output/{slug}/ ``` **Examples:** - "Write a comparison article about email apps for mysite.com" - "I need a how-to guide about email automation for https://example.com" - "Create an alternatives page for Gmail for our domain filomail.com" --- ## Execution Modes | Mode | Time | Focus | Use when | |------|------|-------|----------| | **Express** | 5-10min | Speed + core quality | Quick turnaround, existing traffic | | **Standard** | 15-20min | Balanced depth + optimization | Most articles, balanced goals | | **Expert** | 25-35min | Maximum quality + competitiveness | High-stakes keywords, competitive niches | ### Mode Differences **Express mode shortcuts:** - Basic site crawl: homepage + pricing only - Simplified competition: top 3 competitors, structure analysis only - Streamlined QA: core checklist, skip advanced verification - Target score: 65+ (publishable quality) **Standard mode (default):** - Comprehensive crawl: full discovery + blog analysis - Detailed competition: top 5 competitors + content gaps + authority sources - Complete QA: full scoring + verification + optimization suggestions - Target score: 75+ (solid quality) **Expert mode enhancements:** - Deep intelligence: multi-source crawling + social/review analysis where available - Advanced competition: semantic analysis + opportunity mapping + trend identification - Premium QA: custom scoring + predictive optimization + enhancement recommendations - Target score: 85+ (exceptional quality) --- ## Phase 0: Context Discovery (Automated) ### ⚡ Skip Check If `product_context` file was provided: 1. Read the file 2. Extract: product_name, value_proposition, pricing_model, brand_voice from it 3. Set voice_confidence = MEDIUM (user-provided, assumed accurate) 4. **Skip 0.1 and 0.6 entirely** 5. Proceed directly to 0.2 (blog ecosystem mapping) and 0.3 (keyword research) Only proceed with 0.1 crawling if no `product_context` was provided. ### 0.1 Product Intelligence Crawl the following in parallel. Accept partial results - missing data triggers targeted questionnaire questions, not full failure. **Crawl targets:** ``` Priority 1 (always attempt): / /pricing Priority 2 (attempt if P1 succeeds): /about /features /product Priority 3 (blog ecosystem): /blog /sitemap.xml /robots.txt ``` **Extract:** - `product_name` - inferred from title tags, logo alt text, H1s - `value_proposition` - first meaningful paragraph on homepage - `core_features` - bullet lists, feature sections, navigation items - `pricing_model` - "free" | "freemium" | "$X/month" | "enterprise" - `brand_voice_signals` - collect 10+ sample sentences across pages **JS-heavy site handling:** If web_fetch returns < 500 characters of meaningful text, note the crawl as failed for that page. Do not treat empty HTML as product context. Trigger questionnaire if ≥ 2 Priority 1 pages fail. **⚠️ Discovery failure threshold:** If ≥ 2 Priority 1 pages fail, jump to **Phase 0.6 immediately**. Collect answers from the user, then return here and continue with 0.2–0.4 using the provided context. Do not wait until after the confirmation gate to surface this. **Brand voice detection:** - Prefer blog post samples over homepage (more authentic voice) - Homepage → marketing voice, not writing voice - Derive: formality (1-5), energy (1-5), technical depth (1-5) - If < 3 sample sources available, mark voice_confidence as LOW ### 0.2 Blog Ecosystem Mapping **Discovery order (try all before concluding):** 1. `/sitemap.xml` or `/sitemap_index.xml` → extract all blog/article URLs 2. Try common blog paths: `/blog`, `/articles`, `/resources`, `/learn`, `/insights`, `/content` 3. `robots.txt` → find sitemap reference 4. Fetch homepage → scan navigation links for blog/articles/resources sections 5. Web search: `site:domain.com inurl:blog OR inurl:article OR inurl:post` If steps 1-5 all return < 3 posts: classify as "new" and note it. Do not assume blog doesn't exist - it may use a non-standard path. **Output:** `existing_posts[]` - {title, url, approximate_topic, publish_date} **Site maturity classification:** - **"new"** - < 5 posts (skip complex hub-spoke strategy, use minimal linking) - **"growing"** - 5-20 posts (basic cluster awareness, strategic linking) - **"mature"** - > 20 posts (full hub-spoke strategy, topical clusters) ### 0.3 Keyword Intelligence (Honest Estimation) **⚠️ Without paid tools, keyword research is estimation, not measurement.** This skill uses SERP signals as proxies. Confidence is moderate. The confirmation gate lets you override the selected keyword before writing begins. **Process:** **Step 1 - Derive candidates from topic** ``` Parse user topic → extract intent + entity + modifier Examples: - "best AI email apps" → intent: comparison, entity: email_apps, modifier: AI - "gmail alternatives" → intent: alternatives, entity: gmail, modifier: none - "how to manage email overload" → intent: guide, entity: email_management, modifier: overload Generate 3-5 keyword variants with different modifiers/year combinations ``` **Step 2 - SERP structure analysis (for each candidate)** ``` Search each keyword, analyze first page: - Presence of ads → high commercial intent - Wikipedia / major media → informational intent, difficult to rank for new sites - Domain diversity (5+ different domains) → easier to enter - 1-2 dominant domains → harder, consider long-tail variant - Article types present → comparison tables, how-to guides, listicles ``` **Step 3 - Select primary keyword** ``` Balance: intent_match × brand_relevance × estimated_difficulty Priority: user topic intent > search volume estimation ``` **Step 4 - Derive secondary keywords** ``` - Related searches from SERP - "People also ask" variations - Long-tail question variants for FAQ section - Semantic variants that don't cannibalize primary ``` **Mode differences:** - **Express:** Top 1 keyword only, basic SERP check - **Standard:** 3 candidates analyzed, secondary keywords included - **Expert:** 5 candidates + semantic clustering + opportunity identification ### 0.4 Competitive Intelligence **Extract top 5-8 URLs from SERP for primary keyword.** **Relevance filtering (in order):** 1. Remove: reddit.com, quora.com, news aggregators, social media posts 2. Prioritize: domains with `/product` or `/pricing` → likely direct competitors 3. Check: is content type comparable (article vs article, not forum thread vs article) 4. Keep: best 3-5 relevant results for analysis **Fallback - if fewer than 2 relevant competitor URLs remain after filtering:** - Relax filter: include top-performing forum threads (Reddit/Quora) as **intent signals only** - Extract: what questions users are asking, what solutions they mention - Do NOT use forum posts as content depth benchmarks (word count, structure) - Note in confirmation gate: "Limited competitor articles found - structure based on search intent signals rather than competitive benchmarking" - Default to FAQ-heavy structure since forums indicate question-dominant intent **For each competitor URL:** ``` Fetch and extract: - Approximate word count (rough estimation from text length) - H2/H3 structure → topic map of what they cover - Table/list presence → structured content indicators - External authority sources they cite → potential sources for us - Brand mentions → who they compare against - Content gaps → what they don't cover well ``` **Blocked/failed competitor:** If web_fetch returns 403/blocked, use web_search snippet as proxy for structure. Note it as "estimated" in the research brief. **Mode differences:** - **Express:** Top 3 URLs only, basic structure extraction - **Standard:** Top 5 URLs + gap analysis + authority source identification - **Expert:** Top 8 URLs + semantic analysis + opportunity mapping + trend identification --- ## ⛳ Phase 0.5: Discovery Confirmation Gate (MANDATORY) **This is the only human checkpoint. Nothing is written until you confirm.** Present a structured summary: ``` ═══════════════════════════════════════════════════ DISCOVERY SUMMARY - Confirm before writing begins ═══════════════════════════════════════════════════ 🏢 Product: [detected product name] 📝 Value proposition: [extracted or inferred] 📊 Site maturity: new | growing | mature ([N] posts found) 🎨 Brand voice: formality [X/5] · energy [X/5] · technical [X/5] 🔍 Voice confidence: HIGH / MEDIUM / LOW 🎯 Primary keyword: "[selected keyword]" 📈 Keyword confidence: HIGH / MEDIUM / LOW 🎪 Search intent: comparison | how-to | alternatives | guide | thought-piece 📄 Article type: [auto-selected based on intent] 📏 Target word count: [range based on SERP analysis] 📅 Year in title: YES / NO (see decision rule below) 🏁 Top competitors (will be analyzed for gaps): 1. [url] - [estimated word count] words · [article type] 2. [url] - [estimated word count] words · [article type] 3. [url] - [estimated word count] words · [article type] 💡 Content opportunities identified: ✅ What competitors cover (must include): - [topic 1] - covered by all top results - [topic 2] - covered by majority 🎯 What competitors miss (our advantage): - [gap 1] - opportunity for unique angle - [gap 2] - underserved subtopic 🔗 Internal links available: [N] posts found Top candidates for linking: - [post title] → [url] - relevant for [section] - [post title] → [url] - relevant for [section] ⚠️ Issues found (requires attention): [Only if present] - Brand voice confidence LOW - only 1 source sample available - Pricing page blocked, pricing model estimated from homepage - Keyword confidence MEDIUM - limited SERP signal clarity 🔧 Mode: [express|standard|expert] · Estimated time: [X] minutes ═══════════════════════════════════════════════════ Reply: CONFIRM to proceed, EDIT [aspect] to modify, or provide corrections. ═══════════════════════════════════════════════════ ``` **⚠️ Gate enforcement:** - Wait for user response. Do NOT self-approve and proceed. - If no response: reply "Waiting for your confirmation. Reply CONFIRM to proceed." - If running in automated/subagent context: save summary to `{output_dir}/discovery-summary.md`, then STOP and return control to caller. Never self-approve. - If user replies CONFIRM: proceed to Phase 1. - If user replies EDIT [aspect]: re-derive only that element, re-present summary. **Year-in-title decision rule (applied automatically):** | Article type | Year in title | Logic | |---|---|---| | Comparison / Best-of | YES if ≥ 2 top SERP results include year | Intent is time-sensitive, year increases CTR | | Alternatives page | YES if product category updates frequently | SaaS/tech = yes, traditional tools = no | | How-to / Guide | NO | Intent is evergreen, year limits lifespan | | Thought piece | NO | Ideas aren't time-dependent | | Industry trends | YES | Explicitly time-sensitive content | **If user provides corrections:** - Re-derive only affected elements - Do not restart full Phase 0 - Update summary and re-confirm --- ## Phase 0.6: Fallback Questionnaire (Only if Discovery Incomplete) **Triggered when:** ≥ 2 Priority 1 crawls failed AND no `product_context` file provided. Output a questionnaire designed to be answerable by a human OR their AI assistant reading company documentation: ```markdown # Product Context - [domain] *Can be filled by you or your AI assistant using your docs/website/marketing materials.* ## Required Information (4 questions - 2 minutes) 1. **Product name:** [What do you call your product? e.g., "FiloMail"] 2. **One-sentence description:** [What does it do, for whom? e.g., "AI email client for knowledge workers who get 100+ emails/day"] 3. **Pricing model:** [e.g., "Free + $7/month Pro" or "From $49/month" or "Enterprise quotes only"] 4. **Primary competitor:** [Who do most people compare you against? e.g., "Superhuman" or "Gmail"] ## Brand Guidelines (3 questions - 1 minute) 5. **Writing tone:** formal | professional | friendly | casual | technical [Pick the closest match to how you want to sound] 6. **Competitive approach:** honest-comparison | highlight-differences | avoid-naming [How should we treat competitors in the article?] 7. **Sample sentence that sounds like you:** [Paste one sentence from your website/marketing that captures your voice] ## Content Strategy (optional - enhances output) 8. **Key articles to link to:** [Top 3-5 URLs of your most important blog posts/pages] 9. **Keywords you want to target:** [If you have specific SEO goals beyond the topic] 10. **Content to avoid:** [Anything we should never say, compare, or mention?] ``` > 💾 Save the above as `product-context.md`, then restart with: > > ```yaml > topic: "[your topic]" > domain: "[your domain]" > product_context: "product-context.md" > ``` --- ## Phase 1: Research Brief Generation ### 1.1 Article Blueprint Assembly Based on confirmed Phase 0 data, create structured plan: **H1 optimization:** ``` Format: [Primary Keyword] [Year if applicable] - [Brand Angle] Character limit: 60 characters Examples: ✅ "Best AI Email Apps 2026 - Tested by Email Power Users" (58 chars) ✅ "Gmail Alternatives That Actually Work for Heavy Users" (55 chars) ❌ "The Ultimate Comprehensive Guide to the Best AI-Powered Email Applications in 2026" (82 chars) ``` **H2 Structure mapping:** ``` Based on search_intent + competitor_analysis + brand_angle: Comparison article: ├─ Quick Comparison Table ├─ [Product 1]: [Key differentiator] ├─ [Product 2]: [Key differentiator] ├─ [Product 3]: [Key differentiator] ├─ How to Choose the Right [Category] └─ FAQ How-to guide: ├─ What You Need Before Starting ├─ Step 1: [Action verb + specific outcome] ├─ Step 2: [Action verb + specific outcome] ├─ Step 3: [Action verb + specific outcome] ├─ Common Problems and Solutions └─ FAQ Alternatives page: ├─ Why Look for [Product] Alternatives? ├─ [Alternative 1]: Best for [Use case] ├─ [Alternative 2]: Best for [Use case] ├─ [Alternative 3]: Best for [Use case] ├─ Migration Guide └─ FAQ ``` **Content depth planning:** ``` Target word count = SERP_average × 1.15 (but not exceeding SERP_max × 1.3) If competitors average 2000 words → target 2300 words If competitors range 1500-4000 → target ~2500 words (sweet spot) Mode adjustments: - Express: SERP_average (match competition) - Standard: SERP_average × 1.15 (slight edge) - Expert: SERP_average × 1.25 (substantial edge) ``` ### 1.2 Linking Strategy Development **Internal links planning:** ``` Based on site_maturity + existing_posts analysis: New sites (< 5 posts): ├─ Link to homepage in intro ├─ Link to product/pricing pages where relevant └─ Total internal links: 2-3 maximum Growing sites (5-20 posts): ├─ Identify 2-3 topically related existing posts ├─ Plan natural mentions in relevant sections ├─ Link to hub page if exists └─ Total internal links: 3-5 Mature sites (> 20 posts): ├─ Map article to topical cluster ├─ Always link to cluster hub ├─ Link to 2-4 most relevant siblings ├─ Strategic product page links └─ Total internal links: 5-8 ``` **External links planning:** ``` Entity-based minimum = count(products + tools mentioned) Claim-based minimum = count(statistics + factual claims) Authority-source minimum = 2-3 industry sources This sets a floor, not a quota. Natural mentions drive linking. Examples: "Best Email Apps" article mentioning 8 apps → minimum 8 official site links + 3-5 review/comparison sources + 2-3 industry reports = 13-16 total ``` ### 1.3 Research Brief Output Save as: `{output_dir}/research-brief.md` ```markdown # Research Brief: [Article Title] **Generated:** [timestamp] **Mode:** [express|standard|expert] **Estimated writing time:** [X] minutes ## Article Specification - **Primary keyword:** [keyword] (confidence: [HIGH|MEDIUM|LOW]) - **Secondary keywords:** [keyword1], [keyword2], [keyword3] - **Search intent:** [comparison|how-to|alternatives|guide|thought-piece] - **Target word count:** [range] - **Article type:** [specific template] ## Content Strategy - **H1:** [optimized headline under 60 chars] - **H2 structure:** [planned section headers] - **Unique angle:** [how we differentiate from competitors] - **Content gaps to fill:** [opportunities competitors miss] ## Competition Analysis ### Top Competitors Analyzed 1. [URL] - [word count] - [what they do well] - [what they miss] 2. [URL] - [word count] - [what they do well] - [what they miss] 3. [URL] - [word count] - [what they do well] - [what they miss] ### Content Requirements (to match/exceed competition) - Topics we must cover: [list] - Comparison table: [required|not needed] - FAQ section: [required|optional] ## Linking Plan ### Internal Links ([N] planned) - [Existing post title] → relevant for [section] → [URL] - [Existing post title] → relevant for [section] → [URL] ### External Links (minimum [N]) - Product official sites: [count] (each mentioned product) - Authority sources: [count] (industry reports, studies, expert sources) - Supporting references: [count] (reviews, comparisons, tools) ## Brand Guidelines - **Voice:** formality [X/5] · energy [X/5] · technical [X/5] - **Competitor treatment:** [approach] - **Red lines:** [restrictions if any] ## Next Steps 1. Confirm this brief captures your intent 2. Proceed to content generation 3. Expected delivery: [timestamp] ``` --- ### ✅ Brief Save Checkpoint Confirm `research-brief.md` was saved to `{output_dir}/`. If save failed (permissions, path issue): output brief contents directly in chat and continue. This is not a user gate — no user action required. --- ## Phase 2: Content Generation ### ⚡ WRITE THE ARTICLE NOW Using the confirmed blueprint from Phase 1, write the article section by section: 1. Write H1 (from blueprint) 2. Write intro paragraph (≤ 100 words, keyword in first sentence, use intent-matched template from 2.1) 3. Write each H2 section in order from blueprint, applying rules from 2.2-2.5 as you write. **After each H2, immediately run the 4-point AI-tell check from §3.1 inline** — fix any flagged sentences before moving to the next H2. Do not batch these checks. 4. Write FAQ section (4-6 questions, natural language, schema-ready) 5. Write conclusion with CTA referencing the domain's product/service 6. Apply internal + external linking inline as you write (2.5 rules) - do NOT do a separate linking pass 7. Save complete draft to: `{output_dir}/article-draft.md` Then proceed to **Phase 3.2 and 3.3** (brand voice + authenticity check) on the saved draft. Phase 3.1 AI-tell checks were already run inline during step 3 above. ### 2.1 Opening Section (Critical First 100 Words) **Requirements:** - Primary keyword appears naturally within first 100 words - Direct answer or clear value proposition (no throat-clearing) - Sets expectation for what reader will learn - Matches search intent immediately **Templates by intent:** **Comparison intent:** ``` Looking for [primary keyword]? After testing [N] options with [criteria], here are the [N] that actually deliver [specific benefit]. This guide covers [what you'll learn] based on [timeframe] of hands-on testing. [Quick comparison table preview] ``` **How-to intent:** ``` [Specific outcome] is achievable in [timeframe] if you follow the right steps. This guide walks through [process] that [specific audience] can use to [specific result]. You'll need [prerequisites] and about [time investment]. ``` **Alternative intent:** ``` [Product] is [what it's good for], but it's not perfect for everyone. If you need [specific use case] or prefer [alternative approach], here are [N] alternatives that might work better for your [situation]. ``` ### 2.2 Body Content Standards **Paragraph structure:** - Maximum 3-4 sentences per paragraph - One main idea per paragraph - Vary sentence length: short (5-10 words) + medium (15-20 words) + occasional long (25-30 words) - No sentence exceeds 35 words **Readability targets:** - Flesch Reading Ease: 60-70 (conversational but professional) - Average sentence length: 15-20 words - Passive voice: < 15% of sentences - Grade level: 8-10 (accessible but not dumbed down) **Required content blocks:** ``` Comparison articles: Quick comparison table within first 300 words How-to guides: Numbered steps with clear action verbs Alternatives pages: Migration considerations/switching guide All articles: FAQ section with 4-6 natural language questions All articles: "Last updated: [Month Year]" at bottom ``` ### 2.3 Statistics and Authority Signals (Verification-First Approach) **⚠️ Core rule: Verify before include. Never assert unverified claims.** **For each statistic needed:** ``` 1. Search for the claim via web_search("[statistic] [topic] study") 2. Fetch the claimed source via web_fetch(source_url) 3. Confirm: - The number exists in the source - The methodology matches the claim - The date/sample size is reasonable 4. Only then include: "According to [Source], [stat] ([year study])" If no verifiable source found: - Use hedged language: "Many practitioners report..." / "Industry surveys suggest..." - Or omit the statistic entirely - NEVER fabricate numbers with real-looking sources ``` **For expert quotes:** ``` 1. Find a real person via web_search("[topic] expert" OR "[industry] CEO interview") 2. Fetch a page where they actually said something quotable 3. Quote their exact words with attribution: "[Exact quote]" - [Name, Title, Company] 4. Do NOT paraphrase opinions as direct quotes 5. If no real quote found → use general industry perspective without quote marks Example: ✅ "Email overload reduces productivity by 25% daily" - John Smith, CEO of EmailCorp (2024 interview) ❌ "Email overload is a major productivity killer" - Industry Expert (fabricated) ``` **Authority signal integration (GEO optimization):** ``` These patterns increase AI citation likelihood (directional signals based on observed AI behavior, not peer-reviewed metrics - treat as best practices): - Statistics with attributed sources → higher citation likelihood Format: "According to [AuthoritySource], [specific stat] ([methodology])" - Expert quotes with named attribution → higher citation likelihood Format: "[Exact quote]" - [Name, Title, Company] ([source/year]) - Self-contained passages → more likely to be excerpted by AI Each key point should make sense in isolation (40-60 words) - Definition blocks → cleaner for AI to parse and cite Start major sections with clear definitions "X is [specific definition]. It works by [mechanism]." - Evidence sandwich pattern: Claim → Evidence → Interpretation "Most users prefer X [claim]. A 2024 study of 1000 professionals found Y [evidence]. This suggests Z [interpretation]." ``` ### 2.4 Platform-Specific GEO Optimization **Different AI platforms prioritize different signals. Optimize for all:** **Google AI Overviews (most exposure):** ``` - Prefers: Tables, numbered lists, FAQ schema - Optimization: Lead sections with direct answers - Length: 40-60 word extractable segments - Format: "X is [definition]. Key benefits include [numbered list]." - Citations: Authoritative sources, recent dates ``` **Perplexity (high-intent queries):** ``` - Prefers: Research papers, statistical studies, expert sources - Optimization: Lead with methodology/sample size for studies - Length: Evidence-heavy, detailed explanations - Format: "Research shows [finding] (N=size, method, year)" - Citations: Academic sources, government data preferred ``` **ChatGPT (broad knowledge queries):** ``` - Prefers: Comprehensive explanations, balanced perspectives - Optimization: Cover multiple angles, acknowledge limitations - Length: Thorough but structured explanations - Format: "While X is generally true, Y factors also matter..." - Citations: Diverse sources, balanced viewpoints ``` **Claude (analytical queries):** ``` - Prefers: Logical structure, cause-and-effect explanations - Optimization: Clear reasoning chains, step-by-step logic - Length: Detailed but logical progression - Format: "Because X happens, Y results, leading to Z outcome" - Citations: Analytical sources, case studies ``` **Implementation in content:** ``` For each major section: 1. Lead with Google-optimized direct answer (40-60 words) 2. Follow with Perplexity-optimized evidence (studies, stats) 3. Include ChatGPT-optimized broader context (perspectives, limitations) 4. Structure with Claude-optimized logical flow (cause → effect → outcome) This creates content that performs well across all AI platforms. ``` ### 2.5 Linking Execution **External links - entity-driven, not quota-driven:** ``` Linking philosophy: Every mentioned entity gets its official link, every factual claim gets a source For each product/tool mentioned: ├─ Link to official site (once per unique entity, not every mention) ├─ Use descriptive anchor text: "FiloMail's AI features" not "click here" └─ Open in new tab considerations for user experience For each factual claim: ├─ Link to most authoritative available source ├─ Preference order: official sites > research papers > major media > industry publications ├─ Avoid: personal blogs, paywalled content, competitor comparison articles └─ Verify link works before including Quality over quantity: ├─ 8 high-quality, relevant links > 15 mediocre links ├─ Every link should add value to the reader └─ No linking just to hit a quota ``` **Internal links - relevance-driven:** ``` From Phase 1 internal_links_plan: Body content linking: ├─ Link only if the target article's topic is genuinely discussed in this section ├─ Use contextual anchor text that describes what they'll find ├─ Never force a link to fill a quota └─ Maximum 1 internal link per 300 words to avoid link bloat Further Reading section: ├─ Include hub page link (if exists) ├─ Add 2-3 most topically related sibling articles ├─ Sort by relevance, not recency └─ Brief description of what each linked article covers Hub-spoke strategy (for mature sites): ├─ Always link back to cluster hub from spoke articles ├─ Hub links to all spokes in cluster ├─ Spokes link to 2-4 most related siblings └─ Avoid every-spoke-to-every-spoke linking (dilutes PageRank) ``` --- ## Phase 3: AI Pattern Prevention & Brand Voice Alignment ### 3.1 AI Writing Pattern Detection & Correction **Detection approach:** Generate content in sections, then scan each section for AI patterns. Do not attempt real-time prevention - LLMs cannot self-monitor during generation effectively. **Banned words (immediate rewrite triggers):** ``` delve, tapestry, seamlessly, robust, leverage, harness, elevate, revolutionize, paradigm, synergy, holistic, navigate (as metaphor), mosaic, landscape (as metaphor), game-changer, cutting-edge (unless literally about technology) ``` **Banned phrases (immediate rewrite triggers):** ``` "at the end of the day", "without further ado", "it's no secret that", "in today's fast-paced world", "in conclusion", "in summary", "to sum up", "delve into", "navigate the landscape", "robust solution" ``` **Structural pattern detection:** ``` Em-dash count: Flag if > 3 per article Rhetorical questions as transitions: Flag and rewrite as statements Triple-adjective stacking: "powerful, intuitive, and elegant" → pick one, prove it Conclusion clichés: "In conclusion" → just make your point directly Throat-clearing openers: "It's important to understand that..." → cut filler ``` **AI-tell detection checklist (run after writing each H2 section):** ``` After each H2 section is written, check ONLY these 4 things: □ Banned words: scan for top offenders (delve, tapestry, seamlessly, robust, leverage, revolutionize, synergy, holistic, navigate-as-metaphor, mosaic) □ Long sentences: any sentence > 35 words? Split it. □ Throat-clearing: does the section start with filler? ("It's important to understand that..." / "When it comes to...") → Cut and start with the point. □ Em-dash density: > 1 em-dash per 200 words? Rewrite as full sentences. If any box is checked: rewrite ONLY the flagged sentence(s). Move on. Do not re-scan after fixing. Do not generate a separate Phase 3 report. This check should take < 30 seconds of processing per section. ``` ### 3.2 Brand Voice Calibration **Voice matching system:** ``` Based on Phase 0 brand_voice_signals analysis: Formality level (1-5): ├─ 1-2: Conversational, contractions, casual tone ├─ 3: Professional but approachable, some contractions ├─ 4-5: Formal, full words, corporate tone Energy level (1-5): ├─ 1-2: Calm, measured, understated ├─ 3: Balanced, moderate enthusiasm ├─ 4-5: Energetic, dynamic, exclamatory Technical level (1-5): ├─ 1-2: General audience, explain everything ├─ 3: Some industry terms with context ├─ 4-5: Assumes domain knowledge, technical depth ``` **If Phase 0 voice_confidence was LOW:** Apply conservative defaults: ``` - Formality 3/5: professional but accessible - Energy 3/5: clear and engaging, not hype-y - Technical 2/5: assume general audience unless evidence otherwise ``` **Brand voice consistency check:** ``` After completing full article: 1. Sample 3-4 representative paragraphs 2. Compare tone/voice to original brand_voice_signals 3. Check for voice drift between sections 4. Ensure competitor treatment matches specified approach 5. Verify no red line violations (if specified) If voice inconsistency detected: - Identify sections that drift from brand voice - Rewrite to match established brand voice parameters - Maintain consistency across intro, body, and conclusion ``` ### 3.3 Content Authenticity Verification **Human-like writing patterns:** ``` Sentence variety: Mix of short (5-10 words), medium (15-20), and occasional longer (25-30) Paragraph flow: Logical progression, not just bullet-point compilation Natural transitions: Connect ideas smoothly, not just "Additionally," "Furthermore," Personal perspective: Where appropriate, show judgment/opinion rather than pure data compilation ``` **Read-aloud test:** ``` For key sections (intro, conclusions, CTA): - Does it sound natural when read aloud? - Would you say this in a professional conversation? - Does it sound like press release copy or human communication? If it sounds like a press release → rewrite in conversational professional tone ``` --- ## Phase 4: Quality Assurance System ### 4.1 Automated Link Verification **Process for every external link using web_fetch:** ⚠️ web_fetch is a content extractor, not an HTTP client. It cannot return status codes. Use content-based verification instead. ``` For each external link in the article: 1. Call web_fetch(url, maxChars=500) 2. Evaluate result: - Content returned AND > 200 chars of readable text → PASS - Content is empty, error thrown, or < 50 chars → FAIL (mark as broken) - Content contains "not found", "page doesn't exist", "404" → FAIL - Content looks like a generic homepage when specific page was intended → FAIL 3. Content relevance check: - Do the first 300 chars relate to the claim being cited? - Is the context appropriate (not pulling positive quotes from negative reviews)? 4. If FAIL: search for alternative source, update link, log replacement in QA report Source quality tiers (assess from domain, not HTTP headers): - TIER-A: Official sites, government, major research institutions, established media - TIER-B: Industry publications, well-known blogs, recognized experts - TIER-C: Smaller publications, newer sources (use sparingly) - TIER-D: Personal blogs, questionable sources (avoid) ``` **Failed link resolution:** ``` For each failed/blocked link: 1. Search for alternative source supporting same claim 2. Priority order: Official source > Research paper > Major publication > Industry blog 3. Update content if no equivalent source found 4. Document replacement in QA report ``` ### 4.2 Multi-Dimensional Quality Scoring **Base scoring framework (100 points total):** **SEO Fundamentals (40 points):** ``` - H1 contains primary keyword, under 60 chars [10 pts] - Primary keyword in first 100 words [5 pts] - Primary keyword in at least one H2 [5 pts] - Keyword density 1-2% (not stuffed, not absent) [5 pts] - Logical H2/H3 hierarchy, no skipped levels [5 pts] - Meta description suggested, 150-160 chars [5 pts] - Target word count achieved [5 pts] ``` **Content Quality (30 points):** ``` - Meets search intent (comparison → table, how-to → steps) [10 pts] - Comprehensive coverage (addresses main competitor topics) [5 pts] - Original angle/value (not just rehashing existing content) [5 pts] - Readability: Flesch 60-70, varied sentence length [5 pts] - FAQ section present with natural questions [5 pts] ``` **Linking Excellence (20 points):** ``` - Internal links: minimum met based on word count [5 pts] - External links: entity-based minimum met [5 pts] - All links verified working [5 pts] - Source quality: majority TIER-A/B sources [5 pts] ``` **Brand & Authority (10 points):** ``` - Brand voice alignment with Phase 0 analysis [3 pts] - No AI-tell patterns detected [3 pts] - Statistics/quotes verified with sources [2 pts] - No red line violations [2 pts] ``` **Industry weight adjustments (predefined balanced tables — total always = 100):** ``` Default: SEO 40 Content 30 Linking 20 Brand 10 = 100 SaaS/Tech: SEO 45 Content 20 Linking 25 Brand 10 = 100 E-commerce: SEO 35 Content 40 Linking 15 Brand 10 = 100 Services: SEO 35 Content 35 Linking 15 Brand 15 = 100 Content sites: SEO 35 Content 40 Linking 15 Brand 10 = 100 ``` **Pass thresholds by mode:** ``` Express: 65+ (publishable, good foundation) Standard: 75+ (solid quality, competitive) Expert: 85+ (exceptional quality, maximum competitiveness) ``` ### 4.3 Factual Accuracy Verification **For product information:** ``` Price verification: ├─ Compare stated pricing vs official pricing pages ├─ Check for recent pricing changes via web search ├─ Note currency, billing frequency, tier differences └─ Update content if mismatches found Feature claims: ├─ Verify against official product documentation ├─ Check for feature deprecation/changes ├─ Use conservative language if uncertain └─ Link to official source for each claim ``` **For statistics and studies:** ``` Source validation: ├─ Fetch claimed source via web_fetch ├─ Confirm statistic exists with exact number ├─ Check methodology, sample size, date ├─ Verify context matches how we're using the stat └─ Update or remove if source doesn't support claim Quote accuracy: ├─ Verify quoted text appears in source ├─ Check surrounding context doesn't contradict our framing ├─ Ensure attribution is accurate (name, title, company) └─ Remove or rephrase if context doesn't support usage ``` ### 4.4 Final Quality Report Generate comprehensive QA documentation: ```markdown # QA Report: [Article Title] **Generated:** [timestamp] **Mode:** [express|standard|expert] **Overall Score:** [X]/100 **Verdict:** PASS ✅ | NEEDS REVISION ❌ ## Score Breakdown - **SEO Fundamentals:** [X]/40 pts - **Content Quality:** [X]/30 pts - **Linking Excellence:** [X]/20 pts - **Brand & Authority:** [X]/10 pts ## Critical Issues (must fix before publication) [List any score-blocking issues] ## Warnings (should fix) [List quality improvements] ## Link Verification Results **External Links Checked:** [N] - ✅ Working links: [N] - ❌ Failed links: [N] (see replacement suggestions below) - 🔍 Source quality: [N] TIER-A, [N] TIER-B, [N] TIER-C **Failed links and replacements:** - Original: [failed_url] (404) - Replacement: [new_url] - Verification: ✅ Content supports claim ## Optimization Opportunities [Mode-specific enhancement suggestions] ## Brand Compliance Check - ✅ Voice matches Phase 0 analysis - ✅ No red line violations - ✅ Competitor treatment appropriate - ✅ No AI writing patterns detected ``` **If verdict is FAIL:** Fix ONLY the listed critical issues (targeted edits to `article-draft.md`), verify each fix with a read/grep, then re-run Phase 4. Maximum 3 rounds per Failure Recovery Guardrails §4. If still failing after 3 rounds, proceed to Phase 5 and flag unresolved issues in the delivery package. --- ## Phase 5: Delivery Package & Post-Processing ### 5.1 Article Finalization **Content formatting:** ``` Frontmatter generation: --- title: "[optimized H1]" description: "[150-160 char meta description]" keywords: "[primary_keyword], [secondary_keywords]" author: "[from brand context or default]" date: "[current_date]" updated: "[current_date]" slug: "[url-friendly-slug]" --- Content structure: ├─ H1 (matches title) ├─ Opening paragraph (keyword in first 100 words) ├─ Quick navigation/table of contents (for long articles) ├─ Main content sections ├─ FAQ section ├─ Conclusion with CTA └─ "Last updated: [Month Year]" ``` **Save instructions:** Write the finalized article (wit …(truncated)