Technical Seo

Technical SEO Implementation

This skill is the implementation reference for technical SEO. Use it when you need to add, fix, or optimize SEO elements in code — meta tags, schema markup, Core Web Vitals, crawlability, and GEO.

This skill covers how to implement in code. For the other SEO concerns:

• seo — Strategy and planning (keyword research, content architecture, what to build)
• seo-content — Writing content (briefs, humanized prose, SERP feature targeting)
• seo-audit — Auditing an existing codebase (scan, diagnose, produce action plan)

---

Metadata

Every indexable page needs these elements correct:

• Title tag: 50-60 chars, primary keyword front-loaded
• Meta description: 120-155 chars, includes CTA
• Canonical: self-referencing or correct target
• Robots: no accidental noindex
• Open Graph: og:title, og:description, og:image for social sharing

For detailed specs and code examples, see ON-PAGE-SEO.md.

HTML Structure

• Exactly one H1 per page, contains primary keyword
• No skipped header levels (H1 → H2 → H3)
• Semantic HTML: <header>, <nav>, <main>, <article>, <section>

Crawlability

• robots.txt exists, not blocking important paths
• XML sitemap exists, all important URLs included
• Canonical tags on every page
• No orphan pages, proper internal linking

For detailed crawlability checklist, see TECHNICAL-AUDIT.md.

Core Web Vitals

Target metrics (2026 thresholds):

Note: INP replaced FID as a Core Web Vital in March 2024.

For optimization techniques (LCP, INP, CLS), see TECHNICAL-AUDIT.md.

E-E-A-T & Schema

Required JSON-LD schema: Organization, WebSite, Article/BlogPosting, FAQPage, BreadcrumbList, Person (author).

For schema code examples and author bio templates, see EEAT-AND-SCHEMA.md.

GEO (Generative Engine Optimization)

Optimize for AI-powered search engines:

For GEO techniques, llms.txt implementation, and AI crawler management, see GEO.md.

---

Fix Priorities

When issues are identified, fix in this order:

Priority 1: Critical (Fix Immediately)

• 404 errors and broken links
• Missing or duplicate title tags
• Broken canonical tags
• noindex on important pages
• HTTPS/security issues
• Blocked by robots.txt

Priority 2: High (Fix Within 1 Week)

• Core Web Vitals failures
• Missing meta descriptions
• Multiple H1 tags
• Missing alt text on key images
• Orphan pages (no internal links)
• Missing schema markup

Priority 3: Medium (Fix Within 1 Month)

• Thin content pages
• Header hierarchy issues
• Internal link optimization
• Image optimization (format, compression)
• Anchor text improvements
• Content freshness updates

Priority 4: Low (Ongoing Optimization)

• A/B testing improvements
• Advanced schema types
• International SEO expansion
• New content for topic clusters
• Competitive gap analysis

---

Post-Fix Validation

After applying fixes:

1. Re-crawl the affected pages 2. Verify DOM changes are live 3. Check robots.txt isn't blocking new paths 4. Validate schema with Google's Rich Results Test 5. Test Core Web Vitals with Lighthouse 6. Monitor Search Console for indexing issues

---

Monitoring Cadence

Daily: Check Search Console for crawl errors. Monitor site uptime. Review security alerts.

Weekly: Review Core Web Vitals trends. Check for new 404s. Monitor AI referral traffic. Review ranking changes.

Monthly: Full technical audit. Content freshness review. Backlink profile analysis. Schema validation.

Quarterly: Full SEO strategy review. GEO performance analysis. Content gap analysis.

---

Quick Reference

SEO Specifications

GEO Checklist

---

Supporting Files

• TECHNICAL-AUDIT.md — Core Web Vitals optimization, crawlability, mobile-first, HTTPS
• ON-PAGE-SEO.md — Title tags, meta descriptions, headers, images, internal linking
• EEAT-AND-SCHEMA.md — E-E-A-T implementation, schema markup library (JSON-LD)
• GEO.md — Generative Engine Optimization, llms.txt, AI crawlers, framework-specific SEO

---

Version History

• v3.0 (March 2026): Reframed as implementation reference (auditing moved to seo-audit skill), added cross-references to seo-content and seo skills, standardized meta description spec to 120-155 chars
• v2.0 (December 2025): Added GEO section, AI crawler management, llms.txt, GA4 AI tracking, updated Core Web Vitals (INP), expanded schema library, framework-specific guides
• v1.0 (December 2024): Initial version with technical audit, on-page SEO, basic schema

E-E-A-T & Schema Markup

How to build trust signals that Google (and AI search engines) use to evaluate your content. Plus schema markup you should add — all via "Tell AI:" prompts.

---

E-E-A-T: Why It Matters

Google evaluates content quality using four signals. These affect your rankings and whether AI search engines cite you.

---

Implementing E-E-A-T

Author Pages

Every blog post or content page should link to an author page showing credentials.

Tell AI:

Create an author bio section for blog posts that includes:
- Author name with link to full author page
- Job title and relevant experience
- A 2-sentence bio
- Links to social profiles (LinkedIn, Twitter)
- "Last updated" date on every article

Also create a full /about or /authors/[name] page with:
- Detailed background and qualifications
- Areas of expertise
- Links to published content

Trust Signals Checklist

• [ ] HTTPS active on all pages
• [ ] Contact information visible (email, form, or phone)
• [ ] Privacy policy linked in footer
• [ ] Terms of service linked in footer
• [ ] Content includes citations with sources
• [ ] Dates on all articles (published and last updated)
• [ ] Author attribution on all content

---

Schema Markup (JSON-LD)

Schema tells search engines what your content IS, not just what it says. Claude Code can add all of these for you.

Required Schema (Add These First)

Tell AI:

Add JSON-LD schema markup to the site:

1. Organization schema on homepage:
   - Company name, URL, logo
   - Social media profile links
   - Contact information

2. FAQPage schema on any page with FAQ content:
   - Each question and answer as structured data
   - This is critical for featured snippets and AI citations

3. Article schema on blog posts:
   - Headline, author, publisher
   - Date published and date modified
   - Author with credentials (Person schema)

4. BreadcrumbList on all pages:
   - Home > Category > Current Page path

Validate with Google's Rich Results Test after adding.

FAQPage Schema (Most Important for AI Citations)

FAQPage schema makes your Q&A content machine-readable. Pages with FAQ schema are 3x more likely to appear in AI Overviews.

Tell AI:

Add FAQPage schema to [page URL] for these questions:
- [Question 1]
- [Question 2]
- [Question 3]

Each answer should be a complete, standalone response (2-3 sentences).
Output as JSON-LD in a script tag.

Optional Schema (Add When Relevant)

Tell AI:

Add [Product/HowTo/VideoObject] schema to [page URL]:
- Include all required fields for Google Rich Results
- Validate with Rich Results Test
- Include pricing, ratings, or step information as applicable

GEO (Generative Engine Optimization)

How to get your content cited by AI search engines (ChatGPT, Perplexity, Google AI Overviews). This matters alongside traditional SEO — AI referrals to websites increased 357% year-over-year.

---

SEO vs. GEO

Key Stats (2025):

• AI Overviews appear for 15-30% of queries
• ChatGPT has 400M+ weekly users
• Pages with FAQ schema are 3.2x more likely to appear in AI Overviews
• Content updated within 90 days gets cited 40-60% more

---

GEO Content Techniques

The key insight: AI search engines cite content that is directly quotable — clear answers, specific statistics, and well-structured facts.

Write Answer-First Content

Lead with the direct answer, then explain. AI engines extract the first clear answer they find.

Tell AI:

Restructure [page URL] for AI citation optimization:
- Lead each section with a direct, quotable answer (1-2 sentences)
- Add a TL;DR block at the top summarizing the page in 3-4 sentences
- Include statistics with source citations (e.g., "53% of traffic comes from organic search — BrightEdge, 2024")
- Use tables for any comparisons (AI extracts tabular data well)
- Define key terms explicitly ("X is defined as...")
- Add expert quotes where relevant

GEO Content Checklist

• [ ] Answer-first structure: Lead with direct answers, not buildup
• [ ] TL;DR blocks: Summarize key points at section starts
• [ ] Statistics with sources: Include data with citations (year + source)
• [ ] Expert quotes: Add quotes from recognized authorities
• [ ] FAQ schema: Implement FAQPage markup (see EEAT-AND-SCHEMA.md)
• [ ] Tables for comparisons: AI extracts tabular data well
• [ ] Clear entity definitions: Define key terms explicitly
• [ ] Fresh content: Update within 90 days for best citation rates

---

llms.txt

A new standard that helps AI systems understand your site. Place at yoursite.com/llms.txt.

Tell AI:

Create an llms.txt file for our site with:
- Company name and one-line description
- "About" section (who we are, what we do, our expertise)
- "Services/Products" section with links and descriptions
- "Key Resources" section linking to our best content
- Contact information

Place at /llms.txt with content-type text/plain, UTF-8 encoding.

---

AI Crawler Management

AI crawlers fall into two categories. You want to allow search crawlers (they cite you) and optionally block training crawlers (they just scrape your content).

Tell AI:

Update robots.txt to manage AI crawlers:
- Allow: OAI-SearchBot, PerplexityBot, ChatGPT-User (these cite us in search results)
- Block: GPTBot, ClaudeBot, CCBot, Google-Extended (training crawlers, no direct benefit)

---

Tracking AI Traffic

Set up tracking to see how much traffic comes from AI search engines.

Tell AI:

Set up AI referral tracking in our analytics:
- Create a custom channel group called "AI Tools"
- Include these referrer domains: chatgpt.com, chat.openai.com, perplexity.ai, claude.ai, gemini.google.com, copilot.microsoft.com
- Track as a separate traffic source from regular referrals
- Add a custom event that fires when a visitor arrives from an AI referrer

---

When to Focus on GEO

Start with GEO when:

• You already have content that ranks in traditional search
• You're publishing educational/informational content (not just product pages)
• Your audience uses AI search tools (most B2B SaaS audiences do)

Skip GEO for now if:

• You don't have a blog or content strategy yet
• Your site is purely a web app with no public content
• You're still pre-launch

Priority: Get traditional SEO basics right first (see TECHNICAL-AUDIT.md and ON-PAGE-SEO.md), then layer in GEO techniques.

On-Page SEO

Specifications for every on-page element, with "Tell AI:" prompts to implement each one.

---

Title Tag

Good: On-Page SEO Guide 2025: Complete Optimization Strategies | Brand Bad: SEO SEO Tips SEO Guide SEO Strategies SEO Best Practices

Tell AI:

Review and optimize title tags for these pages: [list URLs]
Each title should:
- Be 50-60 characters
- Front-load the primary keyword
- Include brand name at end (if space allows)
- Be unique (no duplicate titles across pages)

---

Meta Description

Tell AI:

Write meta descriptions for these pages: [list URLs]
Each description should:
- Be 120-155 characters
- Include the primary keyword naturally
- End with a call-to-action (Learn more, Get started, Try free)
- Be unique per page

---

Header Hierarchy

Rules:

• Exactly ONE <h1> per page (contains primary keyword)
• No skipped levels (H1 → H2 → H3, never H1 → H3)
• Use question-based headings for featured snippet targeting
• Include keywords naturally in headings

Tell AI:

Check and fix header hierarchy on [page URL]:
- Ensure exactly one H1 containing the primary keyword
- Fix any skipped header levels
- Convert key headings to question format where appropriate (helps with featured snippets)

---

Image Optimization

Checklist for every image:

• [ ] Format: WebP or AVIF (25-50% smaller than JPEG)
• [ ] File size: < 200KB (ideally < 100KB)
• [ ] Width and height attributes set (prevents layout shift)
• [ ] Alt text: Descriptive, includes keyword naturally (max 125 chars)
• [ ] Filename: SEO-friendly (seo-guide-2025.webp, not IMG_001.jpg)
• [ ] Below-fold images: loading="lazy" attribute
• [ ] Hero/above-fold images: fetchpriority="high" and NO lazy loading

Tell AI:

Optimize all images on [page URL]:
- Convert to WebP format
- Add width and height attributes to prevent layout shift
- Add descriptive alt text with relevant keywords (max 125 chars)
- Add loading="lazy" to below-fold images
- Add fetchpriority="high" to the hero image
- Rename files to be SEO-friendly (descriptive-name.webp)

---

Internal Linking

Good internal linking helps search engines discover pages and distributes authority.

Best practices:

• Use descriptive anchor text (not "click here")
• Link from high-authority pages to pages you want to rank
• Every page should have at least 2-3 internal links pointing to it
• No orphan pages (pages with zero internal links)

Anchor text distribution:

• Descriptive/partial match: 60-70%
• Exact keyword match: 10-20%
• Branded: 10-20%
• Generic ("click here", "learn more"): < 10%

Tell AI:

Audit internal linking structure:
- Find orphan pages (no internal links pointing to them)
- Find pages with weak anchor text ("click here", "read more")
- Suggest 3-5 internal link additions for each key page
- Use descriptive anchor text that includes relevant keywords

Technical SEO Audit

Step-by-step audit process, Core Web Vitals targets, crawlability essentials, and common fix patterns. Focus on what you check and what you ask AI to fix.

---

Running a Technical Audit

When asked to "audit for SEO", check these in order:

1. Metadata Check

For every important page, verify:

Tell AI:

Audit metadata for these pages: [list your important pages]
For each page, check:
- Title tag length and keyword placement
- Meta description length and CTA
- Canonical tag (should point to itself)
- No accidental noindex
Report issues in a table with page URL, issue, and fix.

2. Structure Check

Tell AI:

Check HTML structure for [page URL]:
- Verify exactly one H1 tag per page
- Check header hierarchy (no skipped levels)
- Verify semantic HTML elements are used properly
Fix any issues found.

3. Schema Validation

Check for these JSON-LD schema types (AI can add them all):

Tell AI:

Add JSON-LD schema markup to the site:
- Organization schema on homepage
- FAQPage schema on any page with FAQ content
- Article schema on blog posts (include author, date published, date modified)
- BreadcrumbList schema on all pages
Validate the output with Google's Rich Results Test.

---

Core Web Vitals

These are Google's page experience signals. Your hosting platform handles most of this, but check anyway.

Targets (2025)

How to check: Go to PageSpeed Insights, enter your URL, and review the scores.

Common Fixes

Tell AI:

Optimize Core Web Vitals for [page URL]:

For LCP (page loads too slowly):
- Preload the largest image on the page
- Add fetchpriority="high" to the hero image
- Preconnect to third-party domains (fonts, CDNs)

For INP (interactions feel sluggish):
- Code split heavy JavaScript modules
- Defer non-critical scripts
- Add immediate visual feedback on button clicks

For CLS (layout shifts/jumping):
- Add width and height attributes to all images and videos
- Use aspect-ratio CSS for responsive elements
- Reserve space for ads or dynamic content

---

Crawlability Essentials

robots.txt

Your robots.txt file tells search engines what to crawl. Place it at yoursite.com/robots.txt.

Tell AI:

Create a robots.txt file that:
- Allows all important pages to be crawled
- Blocks admin, cart, checkout, and account pages
- Blocks URL parameters (?utm_, ?session=)
- Allows AI search crawlers (OAI-SearchBot, PerplexityBot, ChatGPT-User)
- Blocks AI training crawlers (GPTBot, ClaudeBot, CCBot, Google-Extended)
- Includes a link to the XML sitemap

XML Sitemap

Your sitemap tells search engines what pages exist. Most frameworks auto-generate this.

Tell AI:

Set up an XML sitemap at /sitemap.xml that:
- Includes all indexable pages
- Includes lastmod dates
- Excludes admin, auth, and utility pages
- Is referenced in robots.txt
Submit it to Google Search Console after deployment.

Canonical Tags

Every page should have a self-referencing canonical tag to prevent duplicate content issues.

Tell AI:

Add self-referencing canonical tags to every page.
For pages with URL parameters (like ?utm_source), the canonical should point to the clean URL without parameters.

---

Mobile-First

Google indexes the mobile version of your site first. Check:

• [ ] Viewport meta tag is set (width=device-width, initial-scale=1.0)
• [ ] Text is readable without zooming (minimum 16px font)
• [ ] Buttons/links are tap-friendly (minimum 48x48px)
• [ ] No horizontal scrolling on mobile

Tell AI:

Verify mobile-first best practices:
- Viewport meta tag is present
- Minimum font size is 16px
- Touch targets are at least 48x48px
- No content overflows horizontally on mobile
Fix any issues found.

---

HTTPS & Security Headers

• [ ] Site loads on HTTPS (not HTTP)
• [ ] HTTP redirects to HTTPS automatically
• [ ] Security headers are set (most hosting platforms handle this)

Tell AI:

Verify HTTPS and security headers:
- Confirm HTTPS is enforced (HTTP redirects to HTTPS)
- Add security headers: Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options
- If using Vercel/Netlify/Railway, check if these are set by default.

---

Audit Report Template

After running an audit, organize findings like this:

Tell AI:

Generate an SEO audit report for [site URL] with:
- Executive summary (overall score, critical/high/medium issue counts)
- Core Web Vitals scores (LCP, INP, CLS with pass/fail)
- Critical issues (fix immediately): broken links, missing titles, noindex errors
- High priority issues (fix this week): missing meta descriptions, multiple H1s, missing schema
- Medium priority issues (fix this month): image optimization, header hierarchy, internal linking
- Recommendations ranked by impact