blog-writing（博客写作）

SEO Blog Writing — Complete Workflow

When to Use

• Writing any blog article (comparison, how-to, listicle, guide, thought piece)
• Creating long-form SEO content (2000+ words)
• Producing content for any website or blog

Execution Model (IMPORTANT)

This skill requires running shell commands (Phase 5 link verification, Phase 6 QA runner). It must be executed in a context with full exec permissions.

Always spawn the writing subagent with security: "full":

sessions_spawn(
  task: "[full article brief]",
  runtime: "subagent",
  security: "full"   ← REQUIRED — without this, exec approval gates block Phase 5 & 6
)

If running in main session directly (fallback only), exec permissions are already sufficient — proceed normally.

Never spawn without security: "full" — the subagent will silently skip QA and deliver an unverified draft.

Failure Recovery Guardrails (Mandatory)

1. Section-by-section writes — Write each H2 section to disk incrementally. Never hold more than one section only in context.
2. Inline AI-tell check — After each H2 section, run the 4-point check (see Phase 3) before moving on. Fix inline, don't batch.
3. QA loop cap — Max 3 QA rounds. Each round fixes only concrete FAIL items from the latest report. Never regenerate passing sections.
4. Timeout recovery — If interrupted mid-article, write partial output to disk immediately, note the resume section, and continue from there. Do not restart from zero.

Pre-Flight

1. Read your product context file (e.g. product/context.md) for current product facts
2. Read your brand guidelines (e.g. brand/voice.md) for voice and red lines
3. Check your internal links map (e.g. blog/plan/internal-links-map.md) for internal linking targets
4. Check your content plan (e.g. blog/plan/content-plan.md) for where this article fits in the topic cluster

Phase 1: Research (Before Writing)

Keyword Research

1. Primary keyword — The exact phrase we want to rank for (e.g., "best AI email apps 2026")
2. Secondary keywords — Related phrases to include naturally (3-5)
3. Long-tail variants — Question-form queries for FAQ section

Competitive Analysis

For the primary keyword, search Google and analyze top 5 results:

• Word count of each
• H2/H3 structure
• What they cover that we should cover
• What they miss that we can fill (content gap)
• External links they use (authority sources)

Run the QA runner to analyze SERP gaps during research:

python3 skills/seo-geo-qa/scripts/seo_qa_runner.py path/to/draft.md --keyword "best email apps for mac"

Use the lower-level analyzer only when debugging SERP gaps in isolation:

python3 skills/seo-geo-qa/scripts/serp_gap_analyzer.py "best email apps for mac" path/to/draft.md
python3 skills/seo-geo-qa/scripts/serp_gap_analyzer.py "best email apps for mac" path/to/draft.md --urls https://competitor1.com https://competitor2.com

Search Intent Classification

Output: Research Brief

Save to your blog plan directory (e.g. blog/plan/) before writing:

## Research Brief: [Title]
- Primary keyword: 
- Secondary keywords: 
- Search intent: 
- Target word count: 
- Top 5 competitor URLs + word counts
- Content gaps to exploit
- Internal links to include
- External authority sources identified

Phase 2: Outline

Standard Article Structure

# H1 — Contains primary keyword, under 60 chars

Opening hook (150-200 words)
- Define the problem/question
- Why this matters now
- What this article covers

## Quick Comparison Table (for comparison articles)

## Detailed Reviews / Sections (bulk of article)
### H3 subsections as needed

## How We Tested / Methodology

## How to Choose / Decision Framework

## FAQ (4-6 questions, schema-markup ready)

## Further Reading (internal + external links)

Heading Rules

• One H1 per article, contains primary keyword
• H2s match search queries where possible
• H3s for subsections within H2s
• Never skip levels (H1 → H3 is wrong)
• Headings describe content, not for styling

Phase 3: Write

Opening (First 100 Words — Critical)

• Primary keyword appears in first 100 words
• Direct answer or clear hook (no throat-clearing)
• Set expectation for what reader will learn

Body Writing Standards

Word Count by Type:

Keyword Density:

• Primary keyword: 1-2% (natural, never stuffed)
• Secondary keywords: 0.5-1% each
• Check: keyword should feel invisible to the reader

Paragraph Structure:

• Max 3-4 sentences per paragraph
• One idea per paragraph
• Short sentences mixed with longer ones
• Use bullet points and numbered lists for scanability

Readability Target:

• Flesch Reading Ease: 60-70 (standard/conversational)
• Grade level: 8-10 (accessible but not dumbed down)
• Sentence length: average 15-20 words, max 35

Internal Linking Strategy

• Link with descriptive anchor text (not "click here")
• Link to related blog posts in the same topic cluster
• Link to product/feature pages where natural
• Follow hub-spoke pattern (see internal-links-map)
• Consult your internal links map (e.g. blog/plan/internal-links-map.md)

External Linking Standards (Proportional)

The principle: Every entity mentioned gets a link. Every factual claim gets a source. Don't link for the sake of linking.

• Prefer: official sites > media reviews > research papers
• Avoid: personal blogs, paywalled content, temporary pages
• Never link to competitors' comparison articles (link to their product page)
• All links must be verified (Phase 5)

Authority Signals (GEO/AEO Optimization)

These boost visibility in AI search engines (ChatGPT, Perplexity, Google AI Overviews):

Evidence sandwich pattern — Structure every major claim as: Claim → Evidence → Interpretation

"Most users prefer [X] [claim]. A 2024 study of 1,000 professionals found Y [evidence]. This means Z for your specific workflow [interpretation]."

Stats without interpretation are noise. Interpretation without evidence is opinion. The sandwich does both and is the format AI systems are most likely to excerpt.

Content Extractability (for AI Citation)

AI systems extract passages, not pages. Each key point should work standalone:

• Lead every section with a direct answer (don't bury it)
• Keep key answer passages to 40-60 words
• Tables beat prose for comparison content
• Numbered lists beat paragraphs for process content
• Self-contained answer blocks that work without surrounding context

Platform-Specific GEO

Different AI systems cite differently. Write each major section to satisfy all four:

In practice: One well-structured section satisfies all four. Lead with direct answer (Google), follow with sourced evidence (Perplexity), add nuance (ChatGPT), ensure logical flow throughout (Claude).

Comparison Article Specifics

For "Best X" / "X Alternatives" / "X vs Y" articles:

• Always include a comparison table at the top
• Each entry needs: Name, Price, Key Feature, Platforms, Best For
• Be honest about competitors — acknowledge strengths
• Be honest about our weaknesses — builds trust, ranks better
• Position your product first but earn it with real arguments
• Include anchor IDs for each product section

Inline AI-Tell Check (Run After Each H2 — Not Batched)

After writing each H2 section, check these 4 things before moving to the next section. Fix inline. Do not save the check for Phase 4.

□ Banned words: delve, seamlessly, robust, leverage, revolutionize, holistic, tapestry,
                navigate (metaphor), harness, paradigm, synergy, game-changer, elevate
□ Long sentences: any sentence > 35 words? Split it.
□ Throat-clearing opener: section starts with "It's important to..." / "When it comes to..."?
  Cut it — start with the point.
□ Em-dash density: > 1 em-dash per 200 words? Rewrite as commas, semicolons, or split sentences.

If any box is checked: rewrite only the flagged sentence(s). Then move on. This takes under 30 seconds per section and catches problems at the source rather than in a painful batch rewrite at the end.

Phase 4: Optimize

SEO Checklist (Before Review)

• [ ] H1 contains primary keyword, under 60 chars
• [ ] Meta description drafted: 150-160 chars, includes keyword
• [ ] Primary keyword in first 100 words
• [ ] Primary keyword in at least one H2
• [ ] URL slug is keyword-rich and clean
• [ ] At least one table or list (featured snippet opportunity)
• [ ] FAQ section present (schema markup ready)
• [ ] "Last updated: [Month Year]" at bottom
• [ ] Internal links ≥ 3
• [ ] External links ≥ 10
• [ ] All images have alt text (when applicable)

AI Writing Pattern Avoidance

CRITICAL: Content must not read like AI wrote it.

Common AI patterns to eliminate:

Self-check: Read the article out loud. If any sentence sounds like a press release, rewrite it.

Phase 5: Link Verification (MANDATORY)

Never deliver content without verifying every link.

Process

1. Extract all URLs from the article
2. Test each with web_fetch or curl -sI
3. Check for: 404, 403, redirects to wrong content, paywalls
4. For non-obvious external sources, run a source-quality spot check (AITDK/Ahrefs/search evidence)

Source Quality Spot Check

For external sources that are not obviously authoritative, check whether they are worth citing:

• AITDK traffic page: https://aitdk.com/traffic/<domain> for traffic / keyword / domain-age hints when accessible
• Ahrefs Backlink Checker: use as a quick proxy for domain strength / backlink profile
• Search evidence: site:domain.com, branded query, and recent indexed pages if third-party tools are blocked

Do not require perfect metrics. The goal is to catch weak, stale, spammy, or irrelevant sources before they land in the article.

When Links Fail

• Search for alternative source supporting the same claim
• Prioritize: Official sites > Research > Major publications
• Update surrounding text if needed
• Document changes:

**Original:** https://broken-link.com (404)
**Replacement:** https://working-link.com
**Reason:** Original returned 404
**Verified:** ✅ Same data confirmed

Quote & Attribution Verification (CRITICAL — learned the hard way)

• If citing a review → verify the quote exists AND the article's overall tone matches your framing
• Tone match test: Read the first 3 paragraphs of the source article. Is it positive, negative, or neutral?

- Source is positive → quote freely - Source is negative → either don't quote, or frame honestly: "Even [Source]'s critical review acknowledged..." - Source is neutral → quote with accurate framing

• Don't pull positive fragments from negative reviews — readers click through and lose trust
• Statistics must match their cited source exactly (number, date, methodology)
• "According to [Source]" → verify Source actually says that

Phase 6: Automated QA (MANDATORY — runs before human review)

After completing Phase 5, ALWAYS run the QA runner before spawning a review agent or delivering the draft. Do not skip this. Do not ask whether to run it.

python3 skills/seo-geo-qa/scripts/seo_qa_runner.py path/to/article.md --keyword "primary keyword"

What happens automatically

1. All links verified (liveness + source quality tiering)
2. Dead links, weak sources, moved links flagged
3. FAQ count, external link count, SERP gap checked
4. Markdown + JSON report saved to qa-reports/{slug}/ next to the article
5. Verdict: PASS or FAIL

If FAIL

• Fix critical issues (dead links, too many TIER-D sources)
• Re-run until PASS
• Max 3 rounds

If PASS

• Proceed to Phase 7 (human review)
• Include the QA report link in the review handoff

Phase 7: Review (Auto-Spawn)

Always spawn a review agent after Phase 6 passes. The review agent checks:

Review must check:

• QA runner verdict is PASS (with report link)
• SEO checklist complete
• Brand voice compliance
• Factual accuracy (pricing, features)
• AI writing patterns eliminated
• Readability standards met

File Conventions

Where to Save

• Research briefs: blog/plan/brief-{slug}.md
• Article drafts: blog/seo/{slug}.md (SEO) or blog/{slug}.md (general)
• Article images: handled separately in your CMS or website repo

Slug Format

• Lowercase, hyphen-separated
• Match target URL path: /blog/{slug}

Title Year Rules (2026-03-24 决策)

• 教育类文章的 freshness 信号放在文末 "Last updated: [Month Year]"
• 比较类文章的年份每年 Q1 集中更新（标题 + 内容 + slug）
• 参考：Anthropic claude.com/blog 零篇使用年份标题，全靠内容 freshness 信号

Related Skills

• content-production — Mandatory produce → review → revise workflow
• content-qa — QA checklist and review agent
• seo-audit — Technical SEO checks for the whole site
• seo-geo — GEO optimization for AI search engines
• competitor-alternatives — Comparison page structure
• schema-markup — JSON-LD implementation
• copy-editing — Multi-pass editing framework