// Comprehensive SEO optimization for web applications. Use when asked to improve search rankings, add meta tags, create structured data, generate sitemaps, optimize for Core Web Vitals, or analyze SEO issues. Works with Next.js, Astro, React, and static HTML sites.
| name | seo-optimizer |
| description | Comprehensive SEO optimization for web applications. Use when asked to improve search rankings, add meta tags, create structured data, generate sitemaps, optimize for Core Web Vitals, or analyze SEO issues. Works with Next.js, Astro, React, and static HTML sites. |
Transform your web application from invisible to discoverable. This skill analyzes your codebase and implements comprehensive SEO optimizations that help search engines and social platforms understand, index, and surface your content.
SEO is not about gaming algorithms—it's about clearly communicating what your content IS to machines (search engines, social platforms, AI crawlers) so they can properly understand and surface it.
Before optimizing, ask:
Core Principles:
The SEO Hierarchy (prioritize in order):
1. Content Quality ← Foundation: Valuable, accurate, unique content
2. Technical Access ← Can crawlers find and index your pages?
3. Semantic Structure ← Do machines understand your content's meaning?
4. Meta Optimization ← Are your titles/descriptions compelling?
5. Structured Data ← JSON-LD for rich search results
6. Performance ← Core Web Vitals affect rankings
ALWAYS analyze before implementing. Different codebases need different approaches.
Identify the framework and routing pattern:
next.config.js, app/ or pages/ directoryastro.config.mjs, src/pages/react-router-domgatsby-config.js, gatsby-node.js.html files in root or public/Check for existing implementations:
<head> (title, description, viewport)og:title, og:image, etc.)twitter:card, twitter:image)<script type="application/ld+json">)sitemap.xml or generation config)Different pages need different SEO approaches:
| Page Type | Priority | Key Optimizations |
|---|---|---|
| Landing/Home | Critical | Brand keywords, comprehensive structured data |
| Product/Service | High | Product schema, reviews, pricing |
| Blog/Article | High | Article schema, author, publish date |
| Documentation | Medium | HowTo/FAQ schema, breadcrumbs |
| About/Contact | Medium | Organization schema, local business |
| Legal/Privacy | Low | Basic meta only, often noindex |
Based on analysis, prioritize:
See references/analysis-checklist.md for detailed audit procedures.
<!-- Required -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{Page Title} | {Site Name}</title>
<meta name="description" content="{150-160 char description}">
<!-- Recommended -->
<link rel="canonical" href="{full canonical URL}">
<meta name="robots" content="index, follow">
Format: {Primary Content} | {Brand} or {Primary Content} - {Brand}
Guidelines:
Title Patterns by Page Type:
Homepage: {Brand} - {Value Proposition}
Product: {Product Name} - {Key Benefit} | {Brand}
Article: {Article Title} | {Brand}
Category: {Category} Products | {Brand}
Search: Search Results for "{Query}" | {Brand}
Guidelines:
DO NOT:
<meta property="og:type" content="website">
<meta property="og:url" content="{canonical URL}">
<meta property="og:title" content="{title}">
<meta property="og:description" content="{description}">
<meta property="og:image" content="{1200x630 image URL}">
<meta property="og:site_name" content="{Site Name}">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@{handle}">
<meta name="twitter:title" content="{title}">
<meta name="twitter:description" content="{description}">
<meta name="twitter:image" content="{image URL}">
See references/meta-tags-complete.md for comprehensive tag reference.
Structured data enables rich search results (star ratings, prices, FAQs, etc.).
| Content Type | Schema | Rich Result |
|---|---|---|
| Organization info | Organization | Knowledge panel |
| Products | Product | Price, availability, reviews |
| Articles/Blog | Article | Headline, image, date |
| How-to guides | HowTo | Step-by-step in search |
| FAQs | FAQPage | Expandable Q&A |
| Events | Event | Date, location, tickets |
| Recipes | Recipe | Image, time, ratings |
| Local business | LocalBusiness | Maps, hours, contact |
| Breadcrumbs | BreadcrumbList | Navigation path |
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "Company Name",
"url": "https://example.com",
"logo": "https://example.com/logo.png",
"sameAs": [
"https://twitter.com/company",
"https://linkedin.com/company/company"
]
}
</script>
Use @graph to combine schemas:
{
"@context": "https://schema.org",
"@graph": [
{ "@type": "Organization", ... },
{ "@type": "WebSite", ... },
{ "@type": "BreadcrumbList", ... }
]
}
See references/structured-data-schemas.md for complete schema examples.
XML Sitemap Requirements:
<lastmod> when content changesFramework implementations: See references/framework-implementations.md
Standard Template:
User-agent: *
Allow: /
# Block admin/private areas
Disallow: /admin/
Disallow: /api/
Disallow: /private/
# Point to sitemap
Sitemap: https://yourdomain.com/sitemap.xml
Always set canonical URLs to:
Handle:
Core Web Vitals affect rankings. Monitor:
| Metric | Target | What It Measures |
|---|---|---|
| LCP | < 2.5s | Largest Contentful Paint (loading) |
| INP | < 200ms | Interaction to Next Paint (interactivity) |
| CLS | < 0.1 | Cumulative Layout Shift (visual stability) |
Quick wins:
❌ Keyword Stuffing
<!-- BAD -->
<title>Best Shoes | Buy Shoes | Cheap Shoes | Shoes Online | Shoe Store</title>
<!-- GOOD -->
<title>Running Shoes for Marathon Training | SportShop</title>
Why bad: Search engines penalize unnatural keyword repetition. Users don't click spammy titles.
❌ Duplicate Descriptions Using the same meta description across multiple pages. Why bad: Misses opportunity for page-specific relevance. Google may ignore and auto-generate.
❌ Description/Content Mismatch Writing descriptions for keywords rather than actual content. Why bad: High bounce rates signal low quality. Users feel deceived.
❌ Missing Alt Text
<!-- BAD -->
<img src="product.jpg">
<!-- GOOD -->
<img src="product.jpg" alt="Blue Nike Air Max running shoe, side view">
Why bad: Accessibility violation. Missed image search opportunity.
❌ Blocking Crawlers Unintentionally
# Accidentally blocking everything
User-agent: *
Disallow: /
Why bad: Complete deindexing. Check robots.txt carefully.
❌ Ignoring Mobile Not having responsive design or mobile-specific considerations. Why bad: Google uses mobile-first indexing. Most traffic is mobile.
❌ Over-Optimization Adding structured data for content that doesn't exist. Why bad: Schema violations can result in penalties. Trust erosion.
❌ Generic Auto-Generated Content
<!-- BAD: Template without customization -->
<meta name="description" content="Welcome to our website. We offer great products and services.">
Why bad: Provides no value. Won't rank. Won't get clicks.
IMPORTANT: SEO implementation should vary based on context.
Vary based on:
Avoid converging on:
// app/page.tsx
import { Metadata } from 'next'
export const metadata: Metadata = {
title: 'Page Title | Brand',
description: 'Page description',
openGraph: {
title: 'Page Title',
description: 'Page description',
images: ['/og-image.png'],
},
}
// pages/index.tsx
import Head from 'next/head'
export default function Page() {
return (
<Head>
<title>Page Title | Brand</title>
<meta name="description" content="Page description" />
</Head>
)
}
---
// src/pages/index.astro
import Layout from '../layouts/Layout.astro';
---
<Layout
title="Page Title | Brand"
description="Page description"
ogImage="/og-image.png"
/>
import { Helmet } from 'react-helmet';
function Page() {
return (
<Helmet>
<title>Page Title | Brand</title>
<meta name="description" content="Page description" />
</Helmet>
);
}
See references/framework-implementations.md for complete guides.
Analyzes a codebase for SEO issues and opportunities:
python scripts/analyze_seo.py <path-to-project>
Output:
Generates sitemap.xml from project routes:
python scripts/generate_sitemap.py <path-to-project> --domain https://example.com
SEO is semantic communication, not algorithm manipulation.
The best SEO:
Focus on making your content findable and understandable. The rankings follow from genuine value clearly communicated.
Claude is capable of comprehensive SEO analysis and implementation. These guidelines illuminate the path—they don't fence it.
Generate professional-quality favicons that rival the best app icons. Uses a multi-layer effects engine with drop shadows, inner glows, highlights, gradients, and noise textures. Includes 8 curated design templates and 18 Lucide icons. Produces complete favicon suites with proper ICO, SVG, PNG formats and framework integration. Trigger when users need favicons, app icons, or browser tab icons.
Smart OG image generation that studies your codebase, understands routes and brand identity, then creates contextually appropriate Open Graph images using Playwright and React components. Triggers: "create og images", "generate social cards", "add open graph images".
Create high-performing YouTube titles and thumbnail text that maximize CTR and virality while maintaining authenticity. Use when analyzing video transcripts to generate title and thumbnail suggestions, optimizing existing titles/thumbnails, or when users request help with YouTube content strategy for click-through rate optimization.
