Optimize SEO

Audit a web page against current SEO best practices (2025-2026) and generate missing or improved elements.

Instructions

Step 1: Identify the Target

Determine what to audit:

HTML file(s): Read the file(s) directly
URL: Use WebFetch to retrieve the page
Component/template: Read the source files that produce the page

If the user provides a URL or file, read it. If unclear, ask what page to optimize.

Step 2: Audit

Consult references/seo-checklist.md for the full checklist and reference material.

Run through each category and report issues:

Title & Meta — Check title tag (50-60 chars, keyword near start, unique), meta description (150-160 chars, keyword + CTA), canonical tag, Open Graph tags, Twitter Card tags.

Headings — Single H1 with primary keyword, logical H2/H3 hierarchy, no skipped levels, no heading tags used for styling.

Images — Alt text on all images, explicit width/height, descriptive filenames, WebP format, lazy loading on below-fold images.

Structured Data — Check for existing JSON-LD. Determine appropriate schema type(s) for the page content (Article, FAQ, Product, LocalBusiness, BreadcrumbList, Organization, etc.).

Internal Linking — Descriptive anchor text, no orphan pages, links to related content.

Content — Primary keyword in first 100 words, comprehensive coverage, author attribution, publication/update dates, external authority links.

Technical — HTTPS, canonical URL, no accidental noindex, mobile-friendly markup, no render-blocking resources.

Step 3: Report Issues

Present findings grouped by severity:

Critical — Missing title tag, no H1, accidental noindex, missing canonical, broken structured data
Important — Missing meta description, missing Open Graph, no structured data, missing alt text, no internal links
Improvements — Title too long/short, meta description could be stronger, missing Twitter Card, image optimization opportunities

For each issue: state what's wrong, why it matters, and the fix.

Step 4: Generate Fixes

Generate the actual markup for all issues found:

Meta tags — Title, description, canonical, robots
Open Graph + Twitter Card — Full tag set
Structured data — Complete JSON-LD block(s) using templates from references/seo-checklist.md
Image attributes — Alt text, width/height, loading="lazy"
Heading restructure — If hierarchy is broken, suggest corrected structure

Apply fixes directly to the file(s) when the user has given edit access. Otherwise, present the generated markup for the user to apply.

Step 5: Validate

After applying fixes:

Confirm structured data is valid JSON (parse it)
Verify title length is 50-60 characters
Verify meta description is 150-160 characters
Check that canonical URL is absolute and correct
Ensure no duplicate tags were introduced

Examples

Example 1: Audit an HTML file

User says: "optimize SEO on src/pages/about.html"

Read the file
Audit against checklist — find: title too long (72 chars), no meta description, no Open Graph tags, images missing alt text, no structured data
Report issues by severity
Generate and apply: shortened title, meta description, full OG + Twitter tags, Organization JSON-LD, alt text for images

Example 2: Generate structured data

User says: "add schema markup to our product page"

Read the product page
Identify it needs Product + BreadcrumbList schemas
Generate JSON-LD from product details on the page (name, price, image, description, availability)
Add the <script type="application/ld+json"> block to <head>

Example 3: Audit a URL

User says: "check SEO on https://example.com/blog/post"

WebFetch the URL
Full audit against checklist
Report all issues with severity
Provide copy-paste markup fixes

Troubleshooting

Page has no `<head>` section

Cause: Single-page app or component that doesn't control the HTML document. Solution: Identify where the <head> is managed (layout file, _app.tsx, index.html) and apply meta tags there. For structured data, JSON-LD can go anywhere in <body>.

Structured data conflicts with existing markup

Cause: Page already has partial or outdated schema. Solution: Merge with existing schema rather than duplicating. Remove deprecated schema types. Validate the combined result.

Dynamic content (SPA/React/Next.js)

Cause: Meta tags need to be set per-route, not just in a static HTML file. Solution: Use the framework's head management (Next.js <Head>, React Helmet, Vue Meta) to set tags per page. Ensure SSR/SSG renders meta tags in the initial HTML response.

optimize-seo