blog-seo-check

name	blog-seo-check
description	Post-writing SEO validation with pass/fail checklist covering title tag length and keyword placement, meta description quality, heading hierarchy and keyword density, internal/external link audit with anchor text analysis, canonical URL verification, Open Graph meta tags (og:title, og:description, og:image), Twitter Card validation, structured data presence and validity, URL structure optimization, and image alt text presence. Produces prioritized fix list with specific recommendations. Use when user says "seo check", "check seo", "validate seo", "blog seo", "seo validation", "on-page seo", "title tag check", "meta description check", "heading check", "link audit".
user-invokable	true
argument-hint	<file-path>
license	MIT

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
Character count	40-60 characters is acceptable, 50-60 ideal, but use as a preview warning because Google truncates by device width
Keyword placement	Primary keyword in first half of title
Power word	Contains at least one power word (e.g., Guide, Best, How, Why, Essential, Proven, Complete)
Truncation risk	No critical meaning lost if truncated at 60 chars
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
Value proposition	Ends with clear reader benefit or value proposition
Keyword presence	Primary keyword appears naturally (not stuffed)
No keyword stuffing	Keyword appears at most once
Call to action	Implies action (learn, discover, find out, see)

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
Keyword in headings	Primary keyword in 2-3 headings (natural, not forced)
Question format	For question-led intent, 60-70% of H2 headings are questions. Otherwise use natural descriptive headings
H2 count	6-8 H2 sections for a standard blog post
Heading length	Each heading under 70 characters

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:

1. Normalize URLs (strip trailing slashes, query parameters, fragments)
2. Score each instance by anchor text descriptiveness (keyword-rich > generic)
3. Recommend keeping the highest-scored instance, removing others
4. 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

FLOW evidence triple (citations)

For every public statistic in the post, verify all three components:

• Year anchor appears in prose ("In 2026," or "As of Q1 2026,") BEFORE the statistic, not buried in parentheses.
• Inline citation names the publisher AND the document title (or report name).
• Source block at the bottom of the post includes the URL plus retrieved YYYY-MM-DD for each cited source.

Posts that fail any of the three either drop the unverifiable claim or replace it with a verified alternative. 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
Length	Short - under 75 characters for the path portion
Keyword presence	Primary keyword or close variant in the URL slug
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
No stop words	Minimal use of "the", "a", "and", "of" in slug
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 length | PASS | 52 chars | - |
| 2 | Title keyword | PASS | "keyword" in first half | - |
| 3 | Title power word | FAIL | No power word found | Add "Guide", "Essential", or "Complete" |
| 4 | Meta description length | PASS | 155 chars | - |
| 5 | Meta description stat | FAIL | No number found | Add a key statistic from the post |
| ... | ... | ... | ... | ... |

### 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:

1. Check credentials: python3 skills/blog-google/scripts/run.py google_auth --check --json
2. If Tier 0+, run PageSpeed: python3 skills/blog-google/scripts/run.py pagespeed_check <url> --json
3. 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
4. If skipped, report the reason: SKIPPED: credentials unavailable, SKIPPED: unpublished URL, or the specific PageSpeed error.