optimise-seo

What this skill does

# Optimise SEO

No visual redesigns or layout changes. Allowed: metadata, structured data, semantic HTML, internal links, alt text, sitemap/robots, redirects, indexing policy, hreflang/i18n, security and privacy headers, error-page status codes, performance tuning.

## Workflow

Copy and track this checklist:

```text
SEO progress:
- [ ] Step 1: Inventory routes and index intent
- [ ] Step 2: Fix crawl/index foundations
- [ ] Step 3: Implement metadata + structured data
- [ ] Step 4: Improve semantics, links, and CWV
- [ ] Step 5: Validate with seo-checklist.md and document changes
```

1. Inventory routes and index intent
2. Fix crawl/index foundations
3. Implement metadata + structured data
4. Improve semantics, links, and CWV
5. Validate with [seo-checklist.md](seo-checklist.md) and document changes

## Must-have
- Sitemap (`app/sitemap.ts`) and robots (`app/robots.ts`):
  ```ts
  // app/sitemap.ts
  import type { MetadataRoute } from "next";
  export default function sitemap(): MetadataRoute.Sitemap {
    return [{ url: "https://example.com", lastModified: new Date() }];
  }
  ```
- Canonicals consistent on every page
- Unique titles + descriptions via `metadata` or `generateMetadata`
- OpenGraph + Twitter Card tags
- JSON-LD: Organization, WebSite, BreadcrumbList (+ Article/Product/FAQ as needed):
  ```tsx
  <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify({
    "@context": "https://schema.org", "@type": "Organization",
    name: "Example", url: "https://example.com"
  }) }} />
  ```
- One h1 and logical heading hierarchy
- Alt text, internal links, CWV targets, mobile/desktop parity

## Programmatic SEO (pages at scale)
- Validate demand for a repeatable pattern before generating pages
- Require unique value per page and defensible data
- Clean subfolder URLs, hubs/spokes, and breadcrumbs
- Index only strong pages; monitor indexation and cannibalization

## SEO audit (triage order)
1. Crawl/index: robots, sitemap, noindex, canonicals, redirects, soft 404s
2. Technical: HTTPS, CWV, mobile parity
3. On-page/content: titles/H1, internal links, remove or noindex thin pages

## Redirects & indexing policy
- Permanent moves use 301/308; temporary use 302/307. Never chain redirects — point straight to the final URL.
- A "not found" page must return a real 404, not 200 with a friendly message (a soft 404 — search engines refuse to index these).
- Give every page an explicit indexing policy: public pages default to `index, follow`; mark staging, admin, thin, or private routes `noindex` (HTML `metadata.robots`) or `X-Robots-Tag` (non-HTML / whole environments).

## Internationalisation (multi-locale sites)
- One URL pattern for all locales; reciprocal `hreflang` with self-ref + `x-default`; translate metadata, not just body; no IP/`Accept-Language` auto-redirects.
- Details and `generateMetadata` pattern: [internationalisation.md](internationalisation.md).

## Technical hardening (security, privacy, resilience)
- Security headers (HSTS, CSP, `nosniff`, `frame-ancestors`, `Referrer-Policy`, `Permissions-Policy`), SRI, cookie flags, `security.txt`.
- Privacy: policy, opt-in cookie consent, Global Privacy Control, cookieless analytics, data minimisation.
- Resilience: correct 404/500 status codes, 503 + `Retry-After`, web app manifest, external monitoring.
- Full guidance: [technical-hardening.md](technical-hardening.md).

## Gotchas
- Don't over-generate thin or doorway pages — indexation drops and quality signals suffer.
- Don't omit canonicals or let them conflict across variants (trailing slash, www, uppercase) — search engines split ranking signal.
- Don't block crawlers unintentionally via `robots.txt`, `noindex`, or auth walls on routes meant to be indexed.
- Don't rely on JS-only rendering without SSR/SSG for indexable content.
- Don't change URLs without 301 redirects — link equity and crawl budget are lost.
- Don't add JSON-LD that doesn't match visible page content — Google treats this as spam and may demote the page.
- Don't return 200 for "not found" or error pages — soft 404s are a quality problem and won't index.
- Don't ship `hreflang` that isn't reciprocal across every alternate — search engines ignore non-mutual sets.
- Don't take a maintenance window down with a 200 or 404 — return 503 + `Retry-After` so the site isn't deindexed.
- Don't add `Strict-Transport-Security` with `preload`/`includeSubDomains` before every subdomain is HTTPS — it's effectively irreversible.

## Resources
- [nextjs-implementation.md](nextjs-implementation.md) — implementation patterns for steps 2-4
- [internationalisation.md](internationalisation.md) — hreflang, URL strategy, localised metadata
- [technical-hardening.md](technical-hardening.md) — security headers, privacy/consent, resilience
- [seo-checklist.md](seo-checklist.md) — pass/fail validation during step 5

## Validation
- Check HTTP response headers for correct status codes and redirects
- Confirm `robots.txt` has correct crawl directives
- Confirm `sitemap.xml` lists all indexed routes with valid URLs
- Verify pages include canonical, OpenGraph, and Twitter Card tags in source HTML
- Run a Lighthouse audit and confirm performance scores meet targets
- Validate JSON-LD with Rich Results Test per URL
- Report remaining blockers with exact URLs and owner/action