technical-seo

Files (6)

• SKILL.md
• core-web-vitals.md
• crawlability.md
• indexation.md
• international-seo.md
• site-architecture.md

SKILL.md (first lines)

# Technical SEO

> **Script location.** If your host does not set `${CLAUDE_PLUGIN_ROOT}`, the scripts are in this plugin's `scripts/` folder, next to `skills/`. Run them with Python 3.10 or newer: `python`, or `python3` where `python` is not found (macOS, many Linux systems).

## When to Use This Skill

Activate this module when the user's request involves any of the following:

- **Core Web Vitals**: Optimizing LCP, INP, or CLS scores; diagnosing page speed issues; interpreting CrUX data or PageSpeed Insights reports
- **Crawlability**: Robots.txt configuration, XML sitemap creation or auditing, crawl budget management, or Googlebot access issues
- **Site Architecture**: URL structure planning, information architecture, internal linking strategy, site depth optimization, or content siloing
- **Indexation**: Canonical tag implementation, noindex/nofollow directives, index bloat, duplicate content resolution, or Google Search Console index coverage issues
- **Redirects**: Redirect chain auditing, 301/302 strategy, redirect maps for site migrations, or HTTP-to-HTTPS migration
- **JavaScript SEO**: Client-side rendering issues, SSR vs CSR vs SSG evaluation, dynamic rendering, or JavaScript crawlability problems
- **Mobile-First Indexing**: Mobile rendering issues, mobile parity checks, responsive design auditing, or mobile usability errors
- **Structured Data**: Schema markup implementation (JSON-LD), rich result eligibility, schema validation, or structured data strategy
- **Log File Analysis**: Server log interpretation, crawl frequency analysis, crawl waste identification, or bot behavior auditing
- **International SEO**: Hreflang implementation, ccTLD vs subdomain vs subdirectory decisions, geotargeting, or multilingual site architecture
- **Security**: HTTPS migration, mixed content resolution, HSTS implementation, or security header configuration
- **HTTP Status Codes**: Diagnosing 4xx/5xx errors, soft 404 detection, server error patterns, or status code strategy
- **Page Speed**: Server response time (TTFB), render-blocking resources, image optimization, code splitting, or CDN configuration
- **Site Migrations**: Domain changes, platform migrations, HTTPS transitions, URL restructuring, or merger/acquisition site consolidation

**Trigger phrases**: "technical seo," "core web vitals," "page speed," "crawl budget," "robots.txt," "sitemap," "redirect," "canonical," "indexation," "noindex," "hreflang," "javascript seo," "mobile-first indexing," "log file analysis," "site architecture," "internal linking," "crawl errors," "HTTP status," "schema markup," "structured data," "site migration," "TTFB," "LCP," "INP," "CLS," "render blocking," "crawlability," "index bloat," "redirect chain," "mixed content," "HTTPS"

## Context efficiency

Heavy skill. **Grep before Read** any referenced file, then `Read` only matched ranges with `offset` + `limit`. List `${CLAUDE_PLUGIN_DATA}/<brand>/` before opening files. On re-invocation mid-session, skip files already in context.

## Brand Context (Auto-Applied)

Before producing any marketing output from this module:

1. **Check session context** — The active brand summary was output at session start. Use the brand name, industry, voice settings, channels, goals, compliance, and competitors shown there.
2. **If you need the full profile**, read: `~/.claude-marketing/brands/{slug}/profile.json`
3. **Apply brand voice** — Formality, energy, humor, authority levels must shape all content tone and word choices
4. **Check compliance** — Auto-apply rules for brand's target_markets and industry using `skills/context-engine/compliance-rules.md`
5. **Reference industry benchmarks** — Consult `skills/context-engine/industry-profiles.md` for the brand's industry
6. **Use platform specs** — Reference `skills/context-engine/platform-specs.md` for character limits and format requirements
7. **Check campaign history** — Run `python "${CLAUDE_PLUGIN_ROOT}/scripts/campaign-tracker.py" --brand {slug} --action list-campaigns` before planning new work
8. **If no brand exists**, say: "No brand profile found. Use /digital-marketing-pro:brand-setup to create one, or I can proceed with general best practices."
9. **Check brand guidelines** — If `~/.claude-marketing/brands/{slug}/guidelines/_manifest.json` exists, load and enforce: `restrictions.md` for banned words, restricted claims, and mandatory disclaimers; `channel-styles.md` for channel-specific tone overrides (may differ from base voice); `messaging.md` for approved key messages, taglines, and positioning language; `voice-and-tone.md` for detailed voice rules beyond the 4 numeric scores. If producing content for a specific channel, channel style rules take precedence over base voice settings.

Do not ask the user for information that already exists in their brand profile.

## Required Context

Before executing technical SEO work, gather:

1. **Website URL**: The domain to audit or optimize
2. **CMS / Platform**: WordPress, Shopify, Webflow, custom, headless, etc. — determines implementation paths
3. **Hosting Environment**: Shared, VPS, dedicated, cloud (AWS/GCP/Azure), CDN provider — affects server-side recommendations
4. **Current Performance Data**: Google Search Console access, PageSpeed Insights scores, CrUX data, or existing audit reports
5. **Site Scale**: Approximate page count (hundreds, thousands, hundreds of thousands) — determines crawl budget relevance
6. **Rendering Method**: Static HTML, server-side rendered, client-side rendered (React/Angular/Vue), hybrid (Next.js/Nuxt) — critical for JavaScript SEO
7. **International Presence**: Target countries and languages, current URL structure for international versions
8. **Known Issues**: Existing problems the user is aware of (crawl errors, indexation drops, speed complaints, ranking losses)
9. **Migration Plans**: Any upcoming domain changes, platform migrations, or URL restructuring
10. **Tech Stack Constraints**: Development team availability, deployment processes, CDN limitations, plugin/extension restrictions

For quick diagnostic requests (e.g., "why is my page slow"), infer reasonable defaults and deliver immediately. For comprehensive audits, gather full context.

## Capabilities

- **Core Web Vitals Optimization**: Diagnose and fix LCP (target < 2.5s), INP (target < 200ms), and CLS (target < 0.1) issues with specific, implementation-ready recommendations; interpret field data (CrUX) vs lab data (Lighthouse) discrepancies; prioritize fixes by user impact
- **Crawlability Audits**: Robots.txt analysis and optimization, XML sitemap structure and validation, crawl budget allocation for large sites, crawl waste identification, orphan page detection, and crawl path optimization
- **Site Architecture Design**: URL structure planning (flat vs hierarchical), information architecture using topic clusters and content silos, internal linking strategy with PageRank flow modeling, click depth optimization (critical pages within 3 clicks), and breadcrumb implementation
- **Internal Linking Optimization**: Link equity distribution analysis, contextual link placement strategy, anchor text optimization, navigation structure auditing, footer and sidebar link strategy, and orphan page rescue
- **Indexation Management**: Canonical tag strategy (self-referencing, cross-domain, parametrized URLs), meta robots directive implementation, X-Robots-Tag HTTP headers, index coverage diagnosis using GSC, index bloat identification and cleanup, and new content indexation acceleration
- **JavaScript SEO**: Client-side rendering assessment, server-side rendering implementation guidance, static site generation recommendations, dynamic rendering as a fallback, Googlebot rendering verification, JavaScript crawl budget impact analysis, and hydration issue diagnosis
- **Mobile-First Indexing**: Mobile rendering parity checks, responsive design validation, mobile usability error resolution, touch target sizing, viewport configuration, and mobile page speed optimization
- **Page Speed Optimization**: TTFB reduction (server tuning, CDN, caching), render-blocking resource elimination, image optimization (format selection, lazy loading, responsive images, preload), CSS/JS minification and code splitting, third-party script auditing, and font loading strategy (font-display, preload, subsetting)
- **Redirect Management**: Redirect chain detection and resolution, 301 vs 302 decision framework, redirect map creation for migrations, redirect loop identification, and redirect performance impact analysis
- **HTTP Status Code Auditing**: 4xx error diagnosis and resolution, 5xx server error pattern analysis, soft 404 detection, 410 Gone implementation for permanently removed content, and status code monitoring strategy
- **Log File Analysis Guidance**: Googlebot crawl frequency and pattern analysis, crawl waste identification (non-indexable URL crawling), response code distribution, crawl budget utilization assessment, and bot vs human traffic ratios
- **Structured Data Implementation**: JSON-LD schema markup for Organization, Product, Article, FAQ, HowTo, BreadcrumbList, LocalBusiness, Event, and Review types; rich result eligibility assessment; schema validation and testing; nested and advanced schema patterns
- **International Technical SEO**: Hreflang implementation (HTML link, HTTP header, XML sitemap methods), ccTLD vs subdomain vs subdirectory decision framework, geotargeting configuration, language and region targeting, and international sitemap strategy
- **Security & HTTPS**: HTTPS migration planning, mixed content detection and resolution, HSTS implementation, security header configuration (CSP, X-Frame-Options, X-Content-Type-Options), and certificate management
- **XML Sitemap Strategy**: Sitemap structure for large sites (sitemap index), image and video sitemaps, news sitemaps, sitemap priority and changefreq guidance, dynamic sitemap generation, and sitemap submission and monitoring
- **URL Structure Optimization**: URL readability and keyword inclusion, parameter handling, trailing slash consistency, URL case sensitivity, and URL length optimization

## Process

**Primary Workflow: Technical SEO Audit & Optimization**

1. **Site Health Snapshot**
   - Pull current Core Web Vitals from CrUX or PageSpeed Insights (LCP, INP, CLS for mobile and desktop)
   - Review Google Search Console index coverage report (valid, excluded, error, warning counts)
   - Check for manual actions or security issues in GSC
   - Note current crawl stats (pages crawled per day, average response time, crawl errors)
   - Baseline: Document current organic traffic, indexed page count, and ranking positions for target keywords

2. **Crawlability Analysis**
   - Review robots.txt for blocking issues (critical resources, CSS/JS, important directories)
   - Validate XML sitemap (well-formed, all important pages included, no non-indexable URLs, within 50K URL / 50MB limit)
   - Assess crawl budget allocation (are crawlers spending time on low-value pages?)
   - Check for crawl traps (infinite calendar pagination, session IDs in URLs, faceted navigation generating millions of URLs)
   - Verify Googlebot can access all critical resources (CSS, JS, images needed for rendering)

3. **Indexation Review**
   - Audit canonical tags across page templates (self-referencing, cross-domain, parameterized URLs)
   - Check for conflicting directives (canonical pointing to page A while noindex is set)
   - Review meta robots directives across templates
   - Identify index bloat (thin content, tag pages, internal search results, parameter variations)
   - Verify pagination handling (paginated series, rel=canonical on component pages)
   - Check for unintended noindex tags (common after staging-to-production migration)

4. **Site Architecture Assessment**
   - Map URL structure and identify depth issues (critical pages beyond 3 clicks from homepage)
   - Analyze internal linking patterns (pages with high/low internal link counts, orphan pages)
   - Evaluate information architecture (logical grouping, topic clusters, content silos)
   - Review navigation structure (header, footer, sidebar, breadcrumbs)
   - Check URL format consistency (trailing slashes, case sensitivity, parameter handling)

5. **Page Speed Deep Dive**
   - **LCP optimization**: Identify the LCP element, check server response time (TTFB < 800ms), audit render-blocking resources, verify image optimization (format, size, lazy loading, preload for above-fold)
   - **INP optimization**: Identify long tasks (> 50ms), audit event handlers, check for main thread blocking, review third-party script impact
   - **CLS optimization**: Check for images/iframes without explicit dimensions, dynamic content injection above the fold, web font loading causing layout shift, ad slot reservations
   - Audit third-party scripts for performance impact (tag managers, analytics, chat widgets, A/B testing tools)

From indranilbanerjee/digital-marketing-pro, MIT.

More from indranilbanerjee/digital-marketing-pro