enhance-web-seo — SEO Audit & Implementation

Google does not rank pages it cannot read, understand, or trust. This skill finds every gap between your app and how search engines see it, then fixes them in order of impact.

Before ANY browser action, read `protocol-browser-anti-stall`.

Phase 0: Detect the stack

package.json        → Next.js Metadata API, remix-utils/seo, @vueuse/head, etc.
src/app/layout.tsx  → existing metadata export (Next.js App Router)
src/app/head.tsx    → legacy Head component
public/robots.txt   → existing robots config
public/sitemap.xml  → existing sitemap

Also check if a sitemap generator is configured (next-sitemap, astro-sitemap, SvelteKit's @sveltejs/adapter-static sitemap, etc.).

Phase 1: Live page audit (Playwright)

For every public-facing route, run the following:

1a. Navigate and capture head

// browser_evaluate after browser_navigate
const seo = await page.evaluate(() => ({
  title: document.title,
  description: document.querySelector('meta[name="description"]')?.content,
  canonical: document.querySelector('link[rel="canonical"]')?.href,
  og_title: document.querySelector('meta[property="og:title"]')?.content,
  og_description: document.querySelector('meta[property="og:description"]')?.content,
  og_image: document.querySelector('meta[property="og:image"]')?.content,
  og_url: document.querySelector('meta[property="og:url"]')?.content,
  twitter_card: document.querySelector('meta[name="twitter:card"]')?.content,
  robots: document.querySelector('meta[name="robots"]')?.content,
  jsonld: [...document.querySelectorAll('script[type="application/ld+json"]')]
            .map(s => s.textContent),
}));

1b. Heading hierarchy

const headings = await page.evaluate(() =>
  [...document.querySelectorAll('h1,h2,h3,h4,h5,h6')]
    .map(h => ({ tag: h.tagName, text: h.textContent.trim().slice(0, 60) }))
);

Rules: exactly one <h1> per page; <h2> never skips to <h4> without <h3>.

1c. Image alt text

const images = await page.evaluate(() =>
  [...document.querySelectorAll('img')]
    .filter(img => !img.alt || img.alt.trim() === '')
    .map(img => img.src.slice(-60))
);

1d. Core Web Vitals

// Measure LCP
const lcp = await new Promise(resolve => {
  new PerformanceObserver(list =>
    resolve(list.getEntries().at(-1)?.startTime)
  ).observe({ type: 'largest-contentful-paint', buffered: true });
  setTimeout(() => resolve(null), 5000);
});
const cls = await page.evaluate(() => {
  let clsScore = 0;
  new PerformanceObserver(list => {
    for (const entry of list.getEntries())
      if (!entry.hadRecentInput) clsScore += entry.value;
  }).observe({ type: 'layout-shift', buffered: true });
  return new Promise(r => setTimeout(() => r(clsScore), 2000));
});

Thresholds: LCP < 2.5 s ✅ / 2.5–4 s ⚠ / > 4 s ❌. CLS < 0.1 ✅ / 0.1–0.25 ⚠ / > 0.25 ❌.

Phase 2: Technical SEO checks

2a. robots.txt

browser_navigate to /robots.txt. Check:

• File exists and returns 200 (not 404)
• No Disallow: / unless intentional (private app)
• Sitemap URL referenced: Sitemap: https://yourdomain.com/sitemap.xml
• No important pages accidentally blocked

2b. Sitemap

Navigate to /sitemap.xml or /sitemap-index.xml. Check:

• Exists and is valid XML
• Contains all important public routes (not just /)
• <lastmod> dates are current, not hardcoded to a past date
• No 404 or noindex pages included

2c. Structured data (JSON-LD)

Validate each JSON-LD block found in Phase 1a:

• @context: "https://schema.org" present
• @type matches the page content (Article, Product, Organization, WebSite, BreadcrumbList, FAQPage, etc.)
• Required fields for the type are present (check references/structured-data-types.md)
• No syntax errors in the JSON

2d. Canonical URLs

• Every page has a <link rel="canonical"> pointing to its definitive URL
• No page canonicalises to a 404 or redirect
• Pagination: page 2+ should have canonical pointing to itself (not page 1)
• Duplicate content (www vs non-www, http vs https): one canonical, one redirect

Phase 3: Research current best practices

CallMcpTool(server: "user-firecrawl", toolName: "firecrawl_search", arguments: {
  "query": "Google SEO best practices Core Web Vitals ranking 2026",
  "limit": 3,
  "sources": [{ "type": "web" }]
})

Also check for framework-specific SEO guidance:

CallMcpTool(server: "user-firecrawl", toolName: "firecrawl_search", arguments: {
  "query": "<framework> SEO metadata structured data 2026",
  "limit": 3,
  "sources": [{ "type": "web" }]
})

Phase 4: Fix — ordered by impact

Priority 1 — Page title and meta description (every page)

Every public page needs a unique, descriptive title (50–60 chars) and meta description (150–160 chars).

Next.js App Router:

// app/page.tsx
export const metadata: Metadata = {
  title: 'Specific Page Title — Brand Name',
  description: 'One or two sentences that describe this page for someone scanning search results.',
};

Next.js dynamic routes:

export async function generateMetadata({ params }): Promise<Metadata> {
  const item = await fetchItem(params.id);
  return {
    title: `${item.name} — Brand Name`,
    description: item.summary,
    openGraph: { title: item.name, description: item.summary, images: [item.coverImage] },
  };
}

Priority 2 — Open Graph and Twitter Card

Required for social sharing previews. Every page needs at minimum:

openGraph: {
  title: 'Page Title',
  description: 'Page description',
  url: 'https://yourdomain.com/page',
  siteName: 'Brand Name',
  images: [{ url: '/og-image.png', width: 1200, height: 630 }],
  type: 'website', // or 'article' for blog posts
},
twitter: {
  card: 'summary_large_image',
  title: 'Page Title',
  description: 'Page description',
  images: ['/og-image.png'],
},

Priority 3 — robots.txt and sitemap

robots.txt (static file at public/robots.txt):

User-agent: *
Allow: /

Sitemap: https://yourdomain.com/sitemap.xml

Sitemap — use the framework's built-in generator where available:

• Next.js App Router: app/sitemap.ts returning MetadataRoute.Sitemap
• SvelteKit: +server.ts returning XML response
• Remix: sitemap[.]xml.ts resource route

Priority 4 — Structured data (JSON-LD)

Add to the relevant page layout:

// For a website home page
const jsonLd = {
  '@context': 'https://schema.org',
  '@type': 'WebSite',
  name: 'Brand Name',
  url: 'https://yourdomain.com',
  potentialAction: {
    '@type': 'SearchAction',
    target: 'https://yourdomain.com/search?q={search_term_string}',
    'query-input': 'required name=search_term_string',
  },
};
// Inject via: <script type="application/ld+json">{JSON.stringify(jsonLd)}</script>

Priority 5 — Core Web Vitals fixes

See audit-bundle-size for JS bundle → LCP fixes. For CLS: ensure images have explicit width/height, fonts use font-display: swap, ads/embeds have reserved space.

Phase 5: Verify with Playwright

After fixes, re-run Phase 1 checks on each modified page. Confirm:

• document.title and meta description match the intent
• OG tags present and well-formed
• JSON-LD valid (no JSON.parse errors)
• LCP improved or within threshold
• No new console errors introduced

SEO audit checklist

Per page:
- [ ] Unique descriptive title (50–60 chars)
- [ ] Meta description (150–160 chars), not cut off
- [ ] Exactly one <h1>
- [ ] Heading hierarchy correct (no skipped levels)
- [ ] All images have alt text
- [ ] Canonical URL present and correct
- [ ] OG title, description, image
- [ ] Twitter card meta
- [ ] JSON-LD structured data where relevant

Site-wide:
- [ ] robots.txt exists and correct
- [ ] Sitemap exists and up to date
- [ ] No important pages noindexed accidentally
- [ ] HTTPS enforced, no mixed content
- [ ] LCP < 2.5 s
- [ ] CLS < 0.1