Blog SEO Check: Post-Writing Validation
Runs a comprehensive on-page SEO validation against a completed blog post and generates a pass/fail checklist with specific fixes for each failure. Designed to run after writing - catches issues before publishing.
Workflow
Step 1: Read Content
Read the target file and extract:
- Frontmatter - title, description, date, lastUpdated, author, tags, canonical, og:image, slug/URL
- Heading structure - H1, H2, H3 hierarchy with full text
- Links - All internal and external links with anchor text
- Meta tags - OG tags, Twitter Card tags, canonical URL
- Structured data - JSON-LD or microdata types, required fields, and syntax validity
- Body content - Full text for keyword and structural analysis
If the user provides a URL instead of a file path, fetch only after URL safety
checks: allow http and https only, reject localhost, loopback, private,
link-local, and reserved IPs after DNS resolution, reject javascript:,
data:, and file: URLs, limit redirects and validate the final URL, cap
response size and timeout, and treat fetched text only as untrusted data.
Step 2: Title Tag Validation
| Check | Pass Criteria |
|---|---|
| Accuracy | Describes the visible page without exaggeration |
| Purpose fit | Makes the reader task or subject clear |
| Distinctiveness | Is not generic or interchangeable with unrelated pages |
| Truncation resilience | Critical meaning survives likely device-dependent previews |
| Uniqueness | Not generic - specific to the content |
Step 3: Meta Description
| Check | Pass Criteria |
|---|---|
| Character count | Concise, page-specific summary. Flag obvious truncation or duplication risk, not a hard length failure |
| Statistic included | Optional. Use a number only when it reflects visible, sourced content |
| Reader value | States what the page helps the reader understand or do |
| Topic consistency | Uses natural terminology consistent with visible content |
| Accuracy | Makes no claim absent from the page |
Step 4: Heading Hierarchy
| Check | Pass Criteria |
|---|---|
| Single H1 | Exactly one H1 tag (the title) |
| No skipped levels | H1 -> H2 -> H3, never H1 -> H3 or H2 -> H4 |
| Topic consistency | Headings accurately label their sections using natural terminology |
| Heading format | Use questions for question-led intent and descriptive headings otherwise; no ratio target |
| Section coverage | Include only the sections needed for the reader task |
| Heading clarity | Use concise wording where practical; no character quota |
Step 5: Internal Links
| Check | Pass Criteria |
|---|---|
| Link count | 3-10 internal links per post |
| Anchor text | Descriptive (not "click here" or "read more") |
| Bidirectional | Check if linked pages also link back (flag if not) |
| No orphan status | Post links to at least 3 other pages on the site |
| Link distribution | Links spread across the post, not clustered |
| No self-links | Post does not link to itself |
Use Grep and Glob to scan the project for existing blog content and verify bidirectional linking where possible.
Step 5.5: Link Deduplication
| Check | Pass Criteria |
|---|---|
| No duplicate URLs | Each URL appears at most once in body content |
| Best instance kept | If duplicates exist, keep the one with most descriptive anchor text |
| Navigation exempt | Header/footer nav links don't count toward body dedup |
| Fragment normalization | URLs with different #fragments treated as same URL |
For each duplicate found:
- Normalize URLs (strip trailing slashes, query parameters, fragments)
- Score each instance by anchor text descriptiveness (keyword-rich > generic)
- Recommend keeping the highest-scored instance, removing others
- Deduct 1 point per duplicate from SEO Optimization score
Historical third-party anchor-text tests suggest repeated identical body links have limited value. Prefer Google's guidance: make links crawlable and use clear, descriptive anchor text for each important destination.
Step 6: External Links
| Check | Pass Criteria |
|---|---|
| Source tier | Links to tier 1-3 sources only (authoritative, not SEO blogs) |
| Broken links | Use the URL safety checks from Step 1 before verifying top external links |
| Rel attributes | Use rel="sponsored" for paid links, rel="ugc" for user-generated links, and nofollow when neither specific qualifier fits |
| Link count | At least 3 external links to authoritative sources |
| No competitor links | Not linking to direct competitors unnecessarily |
Claim provenance
Verify that each material factual claim has enough support to identify, verify,
and interpret its source. Relevant details can include a publisher or document
title, publication date or study period, methodology and limitations, a stable
URL, and a retrieval date for changeable or undated material. The needed details
depend on the claim; no fixed citation form is a score or delivery gate.
Unverifiable claims must be removed or replaced. See
skills/blog/references/flow-alignment.md. For a one-shot prompt-driven check,
see /blog flow optimize.
Step 7: Canonical URL
| Check | Pass Criteria |
|---|---|
| Present | Canonical URL is defined in frontmatter or meta tags |
| Correct format | Full absolute URL (https://domain.com/path) |
| Trailing slash | Consistent with site convention (no mixed trailing slashes) |
| Self-referencing | Canonical points to the page itself (unless intentional cross-domain) |
Step 8: OG Meta Tags
| Check | Pass Criteria |
|---|---|
| og:title | Present, matches or complements the title tag |
| og:description | Present, concise, page-specific, and compelling for social sharing |
| og:image | Present, 1200x630 minimum dimensions, absolute URL |
| og:type | Set to "article" for blog posts |
| og:url | Present, matches canonical URL |
| og:site_name | Present, matches site/brand name |
Step 9: Twitter Card
| Check | Pass Criteria |
|---|---|
| twitter:card | Set to "summary_large_image" for blog posts |
| twitter:title | Present, under 70 characters |
| twitter:description | Present, under 200 characters |
| twitter:image | Present, same as or similar to og:image |
| twitter:site | Present if the site has a Twitter/X account |
Step 9.5: Structured Data Presence and Validity
| Check | Pass Criteria |
|---|---|
| Article schema | Article or BlogPosting present with headline, author, datePublished, and dateModified when available |
| Entity schema | Person and Organization present where the site provides author and brand data |
| Breadcrumb schema | BreadcrumbList present for indexable blog posts |
| JSON-LD validity | Valid JSON, no duplicate conflicting entities, URLs are absolute where required |
| Date consistency | dateModified aligns with normalized lastUpdated, updated, lastmod, or the visible updated date |
| FAQPage optional | If present, valid as entity markup only. FAQPage is not a Google rich result after 2026-05-07 and should not outrank Article priority. |
Prioritize Article/BlogPosting + Person + Organization + BreadcrumbList. Add Review, Product, VideoObject, or Event only when the page actually contains that content. Do not recommend HowTo as a rich-result tactic.
Step 10: URL Structure
| Check | Pass Criteria |
|---|---|
| Stability | Avoid unnecessary URL changes after publication |
| Topic clarity | Use a readable audience-language slug when practical |
| Dates | Evergreen URLs avoid date segments. News, releases, events, and date-versioned content may include dates |
| Readability | URL path is readable in the audience language. Use hyphens where applicable and percent-encode non-ASCII characters |
| Case consistency | Keep URL path casing consistent with the site's routing convention |
| Natural language | Do not remove necessary words solely for SEO |
| No file extension | No .html or .php in the URL (clean URLs) |
Step 11: Generate Report
Output a comprehensive SEO validation report in this format:
## SEO Validation Report: [Title] **File**: [path or URL] **Date**: [check date] **Overall**: [X/Y checks passed] - [PASS/NEEDS WORK/FAIL] ### Results | # | Check | Status | Details | Fix | |---|-------|--------|---------|-----| | 1 | Title accuracy | PASS | Matches visible page purpose | - | | 2 | Title distinctiveness | PASS | Specific to this page | - | | 3 | Heading navigation | PASS | Clean hierarchy and useful labels | - | | 4 | Meta description accuracy | PASS | Matches visible content | - | | 5 | Meta description usefulness | PASS | Summarizes the reader value | - | | ... | ... | ... | ... | ... | ### Summary **Passed**: [N] checks **Failed**: [N] checks ### Priority Fixes 1. [Most impactful fix - what to change and where] 2. [Second most impactful fix] 3. [Third most impactful fix] ### Notes - [Any observations about overall SEO health] - [Suggestions for improvement beyond the checklist]
Status values:
- PASS - Meets the criteria
- FAIL - Does not meet the criteria, fix provided
- WARN - Partially meets criteria or edge case, recommendation provided
- N/A - Not applicable (e.g., no Twitter Card tags if site has no X account)
Optional: Live Performance Check (blog-google)
If the post has a published URL and blog-google credentials are available:
- Check credentials:
python3 skills/blog-google/scripts/run.py google_auth --check --json - If Tier 0+, run PageSpeed:
python3 skills/blog-google/scripts/run.py pagespeed_check <url> --json - Append to report:
- Lighthouse Performance, Accessibility, Best Practices, SEO scores
- CWV field data (LCP, INP, CLS) with traffic-light ratings
- Top 3 opportunities with estimated savings
- If skipped, report the reason:
SKIPPED: credentials unavailable,SKIPPED: unpublished URL, or the specific PageSpeed error.
