laguagu/claude-code-nextjs-skills / skills/nextjs-seo
nextjs-seo
VerifiedNext.js App Router SEO implementation and audits. Use for metadata and social images, sitemap/robots, canonicals and localization, structured data, Core Web Vitals evidence, AI crawler policy or search-indexing diagnosis. Not for general Next.js feature work unrelated to SEO.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.0 KB |
| references/ai-search.md | markdown | 7.1 KB |
| references/checklist.md | markdown | 2.6 KB |
| references/json-ld.md | markdown | 2.2 KB |
| references/metadata-api.md | markdown | 3.7 KB |
| references/sitemap-robots.md | markdown | 2.9 KB |
| references/troubleshooting.md | markdown | 4.3 KB |
references/troubleshooting.md
View on GitHub# SEO diagnosis
Start with an affected production URL and the exact observation. Compare the
complete served response, browser behavior and Search Console evidence;
these describe different layers.
## Indexing and crawl status
“Discovered – currently not indexed” says Google found the URL but has not
crawled it yet, typically because the crawl was rescheduled to avoid overloading
the site. “Crawled – currently not indexed” says a crawl did not result in
indexing. Neither status identifies a single cause or establishes a
content-length problem.
Use URL Inspection and the relevant indexing report to check fetch success,
crawl permission, noindex, declared and Google-selected canonicals. Inspect
redirects, status codes, duplicate intent and whether the page has a distinct
useful purpose. Check server/firewall logs when access is uncertain.
Change robots rules only after confirming the route should be public, and
preserve unrelated restrictions. A robots block can stop discovery of a
noindex directive. Indexing requests are optional follow-up after meaningful
fixes; repeated submissions do not guarantee indexing.
## Content missing from the served HTML
The browser hides this fault, because hydration fills the section in. Fetch the
production URL without JavaScript and search the response for a visible phrase
and a data value from each important section. Count fallback skeletons too.
With Cache Components (Next.js 16), check two causes:
- **The value is in the RSC payload (`self.__next_f`) but not in the markup.**
The server had the data and the prerender left the Client Component out.
Reading the clock or randomness during its render (`Date.now()`, `new Date()`,
`Math.random()`, `crypto.randomUUID()`) stops the prerender at that point, and
the nearest Suspense fallback is what the HTML holds. Libraries do this too:
TanStack Query v5 reads `Date.now()` in `useQuery` for a numeric `staleTime`
and when it builds a query from `initialData` without `initialDataUpdatedAt`,
and `dehydrate()` reads it as well. A `<Suspense>` boundary silences the
build's prerender error by deferring the content, so the error going away does
not mean the content is in the HTML. Keep the read out of server render, for
example `staleTime: isServer ? "static" : ms` with seeded `initialData` and an
`initialDataUpdatedAt` the server passed in, such as `Date.parse(serverTime)`
(tested on Next.js 16.3 with TanStack Query 5.103), or move it to an effect.
- **The value is in neither.** Check the section's `cacheLife`: `revalidate: 0`,
`expire` under 5 minutes or `stale` under 30 seconds exclude it from
prerenders, and it resolves at request time. `stale` under 5 minutes also keeps
it out of the App Shell. For content a crawler must read, keep `stale` and
`expire` at 5 minutes or more and refresh live values on the client.
## Missing or wrong metadata
Compare source and the complete production response for the installed
metadata-streaming mode and relevant bot. Check inheritance, file precedence,
relative URL resolution and the correct deployment origin.
See [metadata-api.md](metadata-api.md).
## Content is stale
Trace the actual publication, cache and invalidation path for the page,
metadata and sitemap. A database read or changed source file is not proof the
deployed route refreshed. Test the real update rather than substituting a
generic cache lifetime.
## HTML is correct but interaction fails
Indexable HTML does not prove hydration. Directly open the route in a
production browser and test buttons, forms and Suspense content. Inspect
console errors, streamed RSC responses, failed assets, client/server initial
state and the deployed proxy.
Test both a direct production load and client navigation: a partially
prerendered route (for example one reading `searchParams`) can serve correct
SEO HTML yet leave its Suspense content unhydrated on a direct load while
working after client navigation. An inactive browser tab can also delay streamed reveal;
rule that out before reporting a failure. Preserve a reproducible case and
investigate the installed framework/configuration.
Use [URL Inspection documentation](https://support.google.com/webmasters/answer/9012289)
for report semantics. State missing credentials, reports or verified bot logs
as limitations instead of inferring them from unrelated exports.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |