Use this skill when implementing on-page SEO fixes in code - meta tags, title tags, heading structure, internal linking, image optimization, semantic HTML, Open Graph and Twitter card tags, and framework-specific SEO patterns. Covers Next.js Metadata API and generateMetadata, Nuxt useSeoMeta, Astro SEO patterns, and Remix meta function. Triggers on any hands-on code task to improve a page's on-site SEO signals.
Use this skill when implementing on-page SEO fixes in code - meta tags, title tags, heading structure, internal linking, image optimization, semantic HTML, Open Graph and Twitter card tags, and framework-specific SEO patterns. Covers Next.js Metadata API and generateMetadata, Nuxt useSeoMeta, Astro SEO patterns, and Remix meta function. Triggers on any hands-on code task to improve a page's on-site SEO signals.
When this skill is activated, always start your first response with the 🧢 emoji.
On-Site SEO
On-site SEO is the practice of optimizing individual page elements in code to improve
search visibility. This skill is the hands-on implementation companion to the broader
SEO strategy skills - it covers everything a developer touches directly: meta tags,
headings, images, links, semantic HTML, and social sharing tags. It is framework-aware,
with concrete code patterns for Next.js, Nuxt, Astro, and Remix. The focus is on
correct, production-grade implementation - not strategy or keyword research.
When to use this skill
Trigger this skill when the user:
Wants to add or fix meta tags (title, description, canonical, robots)
Needs to implement Open Graph or Twitter Card tags
Asks about heading structure (H1, H2, H3 hierarchy) on a page
Wants to add or improve alt text on images
Asks how to implement SEO in Next.js, Nuxt, Astro, or Remix
Needs to optimize images for SEO (alt text, lazy loading, dimensions, format)
Wants to add semantic HTML to improve page structure
Asks about internal linking strategy in code
Do NOT trigger this skill for:
Keyword research or content strategy - use keyword-research skill instead
Performance metrics, Largest Contentful Paint, or Core Web Vitals optimization -
use core-web-vitals skill instead
Key principles
Title tag is the single most impactful on-page element - Keep it under 60
characters, put the primary keyword near the start, make it unique per page. Every
page with a missing or duplicated title tag is leaving ranking signal on the table.
One H1 per page, containing the primary keyword - The H1 is the page's
editorial headline. More than one H1 confuses search engines about the page's topic.
H1 should be distinct from the title tag - not identical - but semantically aligned.
Every image needs descriptive alt text - Alt text is read by screen readers
and indexed by crawlers. Describe the image's subject and context. Do not keyword-
stuff alt text - "golden retriever puppy on grass" beats "dog puppy dog pictures dogs".
Internal links distribute authority and aid discovery - Every page on the site
should be reachable via internal links. Anchor text should be descriptive, not
generic ("see pricing" not "click here"). Use absolute URLs for reliability.
Semantic HTML helps search engines understand page structure - Elements like
, , , , , and communicate
document structure to crawlers without extra markup. Use native elements before
adding schema markup.
<article>
<nav>
<main>
<section>
<header>
<footer>
Core concepts
The on-page SEO hierarchy
Search engines weight on-page signals in this order (highest to lowest impact):
title tag <- URL bar, search snippet title, primary ranking signal
H1 <- editorial headline, should contain primary keyword
meta description <- search snippet body, not a ranking signal but drives CTR
headings (H2-H6) <- content structure, secondary keyword placement
body content <- relevance signals, LSI keywords, readability
images <- alt text, filename, lazy loading, dimensions
internal links <- anchor text, page authority distribution, crawl paths
Meta robots directives
Control crawl behavior with the robots meta tag:
<!-- Default - index the page, follow links --><metaname="robots"content="index, follow"><!-- Block indexing but follow links (e.g. pagination, filtered views) --><metaname="robots"content="noindex, follow"><!-- Block indexing and link following (e.g. admin pages) --><metaname="robots"content="noindex, nofollow"><!-- Allow indexing but don't follow links --><metaname="robots"content="index, nofollow">
Open Graph protocol
OG tags control how pages appear when shared on Facebook, LinkedIn, Slack, and most
social platforms. The minimum required set:
<metaproperty="og:title"content="Page Title Here"><metaproperty="og:description"content="Description (max 300 chars recommended)"><metaproperty="og:image"content="https://example.com/og-image.png"><metaproperty="og:url"content="https://example.com/page"><metaproperty="og:type"content="website">
OG image should be 1200x630px (1.91:1 ratio). Twitter uses twitter: prefixed tags
but falls back to OG tags when Twitter-specific tags are absent.
Canonical URLs
The canonical tag tells search engines which URL is the authoritative version of a
page. Required for: paginated content, filtered/sorted product listings, content
syndicated across multiple URLs, and HTTPS/HTTP or www/non-www variants.
Self-contained content unit - good for blog posts, news items
<main>
Primary page content - signals to crawlers where the content is
<nav>
Navigation landmark - helps crawlers map site structure
<section>
Thematic grouping with a heading - creates content hierarchy
<aside>
Supplementary content - lower priority to crawlers
<header> / <footer>
Page or section framing - not primary content
<time datetime="">
Machine-readable date - helps with freshness signals
Common tasks
1. Set up complete meta tags for a page
The minimum complete set for any page:
<head><!-- Title tag - unique per page, primary keyword near start, max 60 chars --><title>Primary Keyword - Brand Name</title><!-- Meta description - not a ranking signal but drives CTR, max 160 chars --><metaname="description"content="Clear description of what this page offers."><!-- Canonical - prevents duplicate content issues --><linkrel="canonical"href="https://example.com/page-url"><!-- Robots - only needed when deviating from default (index, follow) --><metaname="robots"content="index, follow"></head>
2. Implement Open Graph and Twitter Card tags
<!-- Open Graph (Facebook, LinkedIn, Slack, iMessage previews) --><metaproperty="og:title"content="Page Title"><metaproperty="og:description"content="Page description, max 300 chars."><metaproperty="og:image"content="https://example.com/images/og-1200x630.png"><metaproperty="og:image:width"content="1200"><metaproperty="og:image:height"content="630"><metaproperty="og:image:alt"content="Description of the OG image"><metaproperty="og:url"content="https://example.com/page"><metaproperty="og:type"content="website"><metaproperty="og:site_name"content="Brand Name"><!-- Twitter Card (falls back to OG if twitter: tags are absent) --><metaname="twitter:card"content="summary_large_image"><metaname="twitter:site"content="@twitterhandle"><metaname="twitter:title"content="Page Title"><metaname="twitter:description"content="Page description."><metaname="twitter:image"content="https://example.com/images/twitter-1200x628.png"><metaname="twitter:image:alt"content="Description of the Twitter image">
3. Structure headings correctly
Every page needs exactly one H1. Headings should never skip levels (H1 > H3).
<main><h1>Primary Keyword - Page Main Topic</h1><section><h2>First Major Subtopic</h2><p>Content...</p><h3>Supporting Detail Under Subtopic</h3><p>Content...</p></section><section><h2>Second Major Subtopic</h2><p>Content...</p></section></main>
Anti-pattern to avoid: using heading tags for visual styling. Use CSS classes instead.
4. Optimize images for SEO
<!-- Full SEO-optimized image tag --><imgsrc="/images/golden-retriever-puppy.webp"alt="Golden retriever puppy playing in grass at sunset"width="800"height="600"loading="lazy"decoding="async"
><!-- For above-the-fold images: eager loading + fetchpriority --><imgsrc="/images/hero-banner.webp"alt="Team working in a modern office space"width="1440"height="600"loading="eager"fetchpriority="high"
>
Image SEO rules:
Filename should describe content: golden-retriever-puppy.webp not img_0042.jpg
Always include width and height to prevent layout shift (CLS)
Use modern formats: WebP or AVIF preferred over JPEG/PNG
loading="lazy" on below-fold images; loading="eager" on above-fold
5. Build internal linking patterns
<!-- Good: descriptive anchor text, absolute URL --><ahref="https://example.com/pricing">View our pricing plans</a><!-- Good: contextual link in body content --><p>
Learn more about
<ahref="/guides/seo-strategy">technical SEO strategy</a>
before optimizing individual pages.
</p><!-- Bad: generic anchor text --><ahref="/pricing">click here</a><!-- Breadcrumb navigation - also useful for SEO --><navaria-label="Breadcrumb"><ol><li><ahref="/">Home</a></li><li><ahref="/guides">Guides</a></li><liaria-current="page">On-Site SEO</li></ol></nav>
6. Add semantic HTML to page structure
<body><header><navaria-label="Main navigation"><!-- Primary site navigation --></nav></header><main><article><header><h1>Article Title</h1><timedatetime="2025-03-14">March 14, 2025</time></header><section><h2>Section Heading</h2><p>Section content...</p></section></article><aside><h2>Related Articles</h2><!-- Supplementary content --></aside></main><footer><!-- Site footer --></footer></body>
Signals ambiguous topic to crawlers; dilutes keyword focus
Exactly one H1 per page containing the primary keyword
Missing canonical
Creates duplicate content issues when URLs differ (www vs non-www, trailing slashes)
Add canonical to every page, always pointing to the preferred URL
Title tag over 60 chars
Google truncates it in search results, reducing CTR
Keep title under 60 chars; put important keywords first
Meta description over 160 chars
Truncated in SERPs; the extra text wastes space
Keep meta description under 155-160 chars
Generic alt text
"image.jpg" or "photo" provides zero signal
Describe the image subject and context specifically
"Click here" anchor text
Provides no keyword context to crawlers
Use descriptive anchor text: "view pricing plans", "read the SEO guide"
Missing OG image
Unfurled links show no preview - kills CTR on social
Every page needs a 1200x630px OG image
Missing image dimensions
Causes Cumulative Layout Shift, hurts CLS score
Always include width and height attributes
Heading tags for styling
Uses <h3> because it "looks right" visually
Use CSS classes for visual sizing; use headings for document structure only
Identical meta descriptions
Duplicate descriptions across pages dilute uniqueness
Write unique, page-specific descriptions for every page
noindex on important pages
Accidentally blocking indexation of content pages
Audit robots meta tags and verify Search Console coverage
Gotchas
Next.js generateMetadata does not merge with layout.tsx metadata - If a root layout.tsx defines a metadata export and a page also uses generateMetadata, they do not deep-merge automatically. The page's metadata overrides the layout's at the same key. You must spread the parent metadata explicitly or use metadata.metadataBase at the root level to avoid broken absolute URL generation for OG images.
Canonical self-referencing with trailing slash mismatch causes duplicate content - If the server serves both /page and /page/, and the canonical points to only one form, crawlers still see two URLs. Enforce a consistent URL form at the CDN or server level AND set canonical - don't rely on canonical alone to resolve the conflict.
OG image URL must be absolute, not relative - og:image content must be a full https:// URL. Relative paths like /images/og.png are not followed by most social crawlers. Always include the full domain, including in framework configurations like Next.js metadataBase.
noindex on paginated pages blocks discovery of linked content - Adding noindex to ?page=2 and beyond is a common SEO mistake. Crawlers still follow links from those pages to discover new URLs. The correct approach for pagination is using <link rel="canonical"> pointing to page 1 or letting Google handle pagination discovery naturally.
title tag set in JavaScript renders too late for crawlers - Client-side JS that sets document.title after load is not reliably indexed by crawlers or used for social previews. Always set title tags server-side in the <head>, never via document.title = ... after hydration.
References
For detailed framework-specific SEO patterns, load the relevant reference file:
references/nextjs-seo.md - Next.js App Router Metadata API, generateMetadata,
sitemap.ts, robots.ts, dynamic OG images with next/og
references/nuxt-seo.md - Nuxt 3 useSeoMeta, useHead, nuxt-seo module, OG image
generation, sitemap and robots modules
references/astro-seo.md - Astro SEO component patterns, content collections with
frontmatter SEO, sitemap integration, astro-seo package
references/remix-seo.md - Remix meta function (V2 convention), loader-based dynamic
meta, parent route meta merging, canonical URLs
For related skills:
Load schema-markup skill for JSON-LD structured data implementation
Load core-web-vitals skill for LCP, CLS, INP performance optimization
Load technical-seo skill for crawlability, rendering strategy, and site architecture
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
