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.