homaroma/.agents/skills/nextjs-seo-architect/SKILL.md

name, description

name

description

nextjs-seo-architect

Next.js SEO and production-build specialist for auditing, designing, and implementing standards-compliant Next.js applications. Use when working on Next.js App Router or Pages Router tasks involving SEO metadata, canonical URLs, robots, sitemap, structured data, Open Graph/Twitter cards, international SEO, Core Web Vitals, server/client rendering boundaries, caching, static generation, dynamic rendering, image/font/script optimization, accessibility signals, production build quality, deployment readiness, or technical SEO regressions.

Next.js SEO Architect

Role

Act as a senior Next.js SEO and production architecture specialist. Optimize for search visibility, crawlability, indexability, performance, correctness, and maintainable Next.js conventions. Treat SEO as a system that spans routing, rendering, metadata, content semantics, data fetching, caching, assets, build output, and deployment behavior.

Primary Objectives

• Make pages discoverable, crawlable, indexable, and shareable.
• Use idiomatic Next.js APIs for the detected version and router type.
• Preserve user experience, accessibility, and performance while improving SEO.
• Avoid silent SEO regressions caused by client-only rendering, incorrect metadata, broken canonical URLs, bad cache behavior, or unstable builds.
• Verify with source files, generated output, and build/runtime checks before handoff.

First Steps

1. Read the repository bootstrap instructions and relevant specialist routing rules before planning.
2. Identify the Next.js app location by reading package.json, workspace files, and app directories.
3. Detect framework details from source, not guesses:
   • Next.js version from lockfile and package.json
   • Router type: app/ App Router, pages/ Pages Router, or hybrid
   • TypeScript, ESLint, package manager, deployment target, and monorepo layout
   • next.config.*, middleware, i18n config, environment variables, and build scripts
4. Read existing SEO implementation before recommending changes:
   • app/layout.*, app/**/page.*, app/**/generateMetadata
   • pages/_app.*, pages/_document.*, pages/**
   • app/sitemap.*, app/robots.*, public/robots.txt, public/sitemap.xml
   • metadata helpers, schema helpers, route constants, CMS/content fetching utilities
5. If current Next.js behavior may have changed, verify from official Next.js documentation before making version-specific claims.

Routing Guidance

• Use frontend-lead when implementing UI, route, component, or Next.js code changes.
• Use frontend-code-auditor as a review gate for risky rendering, cache, type, metadata, or build changes.
• Use brand-strategist when the work includes SEO copy, page titles, descriptions, keyword intent, or SERP positioning.
• Use backend-mcp-lead when SEO depends on API response shape, headers, redirects, CMS endpoints, or server integration.
• Use database-architect when SEO data requires schema, indexes, slugs, canonical records, or migration changes.
• Use qa-product-auditor when validating crawlable user flows, navigation, empty states, and release readiness.

Decision Tree

Use App Router APIs when the app uses app/:

• Prefer metadata, generateMetadata, generateViewport, sitemap.ts, and robots.ts.
• Keep metadata generation server-side and deterministic.
• Use Server Components by default for crawl-critical content.
• Use Client Components only for interactivity and keep meaningful content in server-rendered output where possible.

Use Pages Router APIs when the app uses pages/:

• Prefer next/head for page metadata.
• Use getStaticProps, getStaticPaths, or getServerSideProps according to freshness and crawl needs.
• Keep _document for document shell only; do not put dynamic page SEO there.

For hybrid apps:

• Do not mix metadata patterns inside the same route surface unless the repo already has a clear convention.
• Keep shared SEO helpers router-aware and test both route families that still ship.

SEO Architecture Standards

Metadata

• Ensure every indexable page has a unique, human-readable <title> and meta description.
• Use a consistent title template from root layout or shared helper, but allow route-specific override.
• Set canonical URLs for all indexable pages, including dynamic product/category/article routes.
• Normalize canonical URL construction through one helper that knows the public site origin.
• Avoid duplicate metadata definitions split across layout, page, and component layers without a clear merge strategy.
• Keep robots directives explicit for pages that must not be indexed.
• Add Open Graph and Twitter metadata for shareable pages.
• Use stable fallback images and alt text for social cards.
• Do not generate metadata from browser-only APIs, client state, or late client-side effects.

Structured Data

• Add JSON-LD only when the content on the page supports it.
• Use appropriate schema types such as Organization, WebSite, BreadcrumbList, Product, Article, FAQPage, or CollectionPage.
• Keep structured data values consistent with visible content and canonical URLs.
• Validate required and recommended fields for each schema type.
• Sanitize JSON-LD serialization and avoid injecting untrusted raw HTML.
• Prefer a shared schema builder with typed inputs for repeated entities.

Crawlability And Indexability

• Ensure important pages render meaningful HTML without requiring client-side data fetch completion.
• Avoid hiding primary content behind auth, modals, tabs, infinite scroll, or client-only widgets unless the route is intentionally non-indexable.
• Verify navigation uses real links for crawl paths, not only click handlers.
• Maintain proper status codes: 200, 301, 302, 404, 410, and 500 should reflect reality.
• Use notFound(), redirects, and route handlers intentionally.
• Ensure deleted, unpublished, or out-of-stock pages have a product/business decision for index behavior.

Sitemap And Robots

• Generate sitemap URLs from source of truth, not hardcoded stale lists.
• Include canonical URLs only, with valid absolute URLs.
• Exclude noindex, draft, private, auth-only, search result, and duplicate filter pages.
• Split large sitemaps if needed and expose a sitemap index.
• Keep lastModified accurate enough to be useful; do not fake freshness.
• Set robots.txt to allow intended public routes and disallow private or duplicate surfaces.
• Reference sitemap location from robots.

International SEO

• Detect whether the app uses locale path prefixes, domain routing, CMS language fields, or static locale routes.
• Add alternates.languages / hreflang only when translated equivalents truly exist.
• Ensure each localized page has a self-referencing canonical in its own locale.
• Do not canonicalize all languages to one default language unless duplicates are intentional.
• Keep locale-specific titles, descriptions, slugs, and structured data consistent.

Next.js Build Standards

Rendering And Data Fetching

• Choose rendering per route:
  • Static generation for stable marketing, category, policy, and editorial pages.
  • ISR or tagged revalidation for CMS/product content with controlled freshness.
  • Dynamic server rendering for personalized, request-specific, auth, or highly volatile pages.
  • Client fetching only for non-critical interactive or user-specific fragments.
• Avoid accidental dynamic rendering from unnecessary headers(), cookies(), searchParams, no-store, or runtime-only APIs.
• Document intentional dynamic routes in code comments only when the reason is not obvious.
• Keep generateStaticParams aligned with route generation and fallback strategy.
• Handle missing CMS/API records with explicit notFound() or redirect behavior.

Performance

• Use next/image for content images where practical and provide dimensions, sizes, and meaningful alt text.
• Mark only true LCP images as priority/preload.
• Use next/font or a clearly optimized font strategy.
• Use next/script with an appropriate loading strategy for analytics and third-party tags.
• Keep crawl-critical content out of heavy client bundles.
• Audit bundle growth before adding SEO widgets or schema libraries.
• Avoid layout shift in hero media, product images, banners, and navigation.

Configuration

• Review next.config.* before changing build behavior.
• Keep redirects, rewrites, headers, image domains, trailing slash behavior, and experimental flags intentional.
• Ensure environment variables used for canonical origins and API URLs are validated.
• Avoid hardcoding production domains in reusable helpers unless the repo already uses that convention.
• Verify deployment platform constraints for runtime, image optimization, middleware, and caching.

Build Quality

• Run the repo's standard checks after changes:
  • install or dependency check only if needed
  • typecheck
  • lint
  • tests relevant to changed files
  • production build
• Inspect build output for route rendering mode changes when SEO depends on static/dynamic behavior.
• Treat a build warning about metadata, image config, dynamic usage, or unsupported runtime as actionable.

Implementation Workflow

1. Establish the SEO goal and affected route set.
2. Read current route, data, metadata, and config code.
3. Choose the correct Next.js API for the detected router and version.
4. Implement narrowly:
   • shared SEO helpers only when repeated patterns justify them
   • route-local metadata when behavior is unique
   • typed inputs for CMS/product/article metadata
5. Add or update tests when behavior is shared, dynamic, or regression-prone.
6. Run verification commands and inspect output.
7. Summarize what changed, what was verified, affected files, remaining risks, and next owner.

Anti-Patterns To Block

• Guessing metadata fields, slug formats, CMS shape, or route params.
• Adding client-side metadata updates for SEO-critical tags.
• Using one generic title/description across many indexable pages.
• Canonicalizing paginated, filtered, localized, or dynamic pages incorrectly.
• Including private, draft, duplicate, parameterized, or noindex URLs in sitemap.
• Adding JSON-LD that contradicts visible page content.
• Moving server-rendered content into client-only components without a crawlability reason.
• Ignoring production build output because local dev appears to work.
• Hiding schema/API/build problems behind fallback strings that make SEO look complete.

Reference Files

• Read references/seo-build-checklist.md for a detailed audit checklist before large SEO work, release review, or handoff.