seo

name	seo
description	SEO audit and optimization skill for Shopify stores. Run /seo audit <url> for a full scored SEO health report with Quick Wins in under 5 minutes — no API keys required.
argument-hint	audit <url> | technical | onpage | content | schema | keywords | competitor
license	MIT

SEO -- Shopify SEO Audit & Optimization

Comprehensive SEO health analysis for Shopify stores. Orchestrates 7 sub-skills and 6 audit agents to produce a scored report with prioritized action items. Works from URL crawl alone -- no API keys required.

Quick Reference

Command	What it does
/seo audit <url>	Full Shopify SEO audit with parallel subagent delegation
/seo audit	Full audit using Karved Concepts preset (karvedconcepts.com)
/seo technical <url>	Technical SEO only -- crawl health, HTTPS, redirects, canonical, sitemap
/seo onpage <url>	On-page scoring -- titles, meta descriptions, H1s, alt text, internal links
/seo content <url>	Content quality audit -- thin pages, keyword coverage, freshness
/seo schema <url>	Structured data validation -- Product, Organization, BreadcrumbList, FAQ
/seo keywords <url>	Keyword opportunity mapping from drinkware keyword database
/seo competitor <url>	Competitor content gap and organic ranking analysis

Context Intake (Required -- Always Do This First)

Before any audit or analysis, collect this context. Without it, recommendations will be generic and may miss Shopify-specific issues.

Ask these questions upfront (combine into one message):

1. Store URL -- Which Shopify store should be audited?
   • Accept any format: karvedconcepts.com, https://karvedconcepts.com, karved-dev.myshopify.com
   • If no URL is provided in the command:
     1. Read ~/.claude/skills/seo/profiles/karved.json
     2. Set store URL to the store_url field (karvedconcepts.com)
     3. Set industry to the industry field (custom_drinkware)
     4. Load primary_keywords as the keyword baseline for this audit
     5. Set b2b_enabled flag to activate B2B-specific checks
     6. Set print_technologies for content and keyword relevance scoring
     7. Announce: "No URL provided. Using Karved Concepts preset (karvedconcepts.com)."
     8. Proceed directly to audit -- do NOT ask for URL, industry, or scope again
2. Industry / Store type -- Which best describes the store? Custom drinkware . Promotional products . Apparel . General e-commerce . B2B wholesale . Other
3. Audit scope -- Full audit or specific area? Full . Technical only . On-page only . Content only . Schema only . Keywords only . Competitor only

If the user provides context upfront (e.g. "/seo audit karvedconcepts.com, it's a custom drinkware store"), extract context from that and proceed without re-asking.

Use the provided context to:

• Select the correct industry benchmarks from references/benchmarks.md
• Apply Shopify-specific checks from references/shopify-seo.md
• Load drinkware keyword database from references/drinkware-keywords.md when industry is drinkware
• Calibrate severity scoring based on store size and industry norms

Orchestration Logic

When /seo audit is invoked:

1. Collect context (see Context Intake above -- do this first)
2. Run crawl_store.py against the target URL to collect page data
3. Spawn sub-skills in parallel: seo-technical, seo-onpage, seo-content, seo-schema
4. Spawn agents in parallel: audit-speed, audit-backlinks
5. Aggregate results into SEO-AUDIT-REPORT.md with overall SEO Health Score (0-100)
6. Generate SEO-ACTION-PLAN.md sorted Critical > High > Medium > Low
7. Generate SEO-QUICK-WINS.md for Critical/High issues fixable in under 15 minutes

For individual commands (/seo technical, /seo onpage, etc.):

• /seo technical <url> -- dispatch to seo-technical sub-skill directly
• /seo onpage <url> -- dispatch to seo-onpage sub-skill directly
• /seo content <url> -- dispatch to seo-content sub-skill directly
• /seo schema <url> -- dispatch to seo-schema sub-skill directly
• /seo keywords <url> -- dispatch to seo-keywords sub-skill directly
• /seo competitor <url> -- dispatch to seo-competitor sub-skill directly

Always collect context first if not already provided.

Quality Gates

Hard rules -- never violate or override these in any recommendation:

• Duplicate title tags = Critical: Any page sharing a title tag with another page is a Critical finding -- never downgrade to High or Medium
• Missing canonical on duplicate content = Critical: Shopify collection filter URLs (/collections/tumblers?sort_by=...) without canonical tags = Critical
• Missing H1 = Critical: Every crawled page must have exactly one H1 -- zero or multiple H1s is Critical
• Non-HTTPS URLs = Critical: Any HTTP asset or page link is Critical -- no exceptions
• Broken internal links = Critical: Any 404 response from an internal link is Critical
• Missing meta description = High: Empty meta descriptions lose CTR on SERP -- always High severity
• Missing robots.txt or sitemap.xml = High: Both files must be present and valid XML/text
• Thin content < 300 words on product/collection pages = High: Qualifies for Quick Wins list if the fix is adding existing product copy
• Missing Product schema on product pages = High: Shopify product pages without JSON-LD Product structured data lose rich results eligibility
• Missing image alt text > 20% of images = High: Accessibility and SEO combined -- any page exceeding this threshold is High

These rules apply globally across all sub-skills and agents. When a sub-skill detects any of the above conditions, it MUST use the specified severity level. The scoring system in references/scoring-system.md applies multipliers based on these severity levels -- the gates ensure the severity classification itself is never weakened.

Reference Files

Load these on-demand as needed -- do NOT load all at startup.

Path resolution: All references are installed at ~/.claude/skills/seo/references/.

• references/scoring-system.md -- Weighted scoring algorithm and grading thresholds
• references/benchmarks.md -- SEO benchmarks by industry
• references/shopify-seo.md -- Shopify-specific SEO gotchas
• references/drinkware-keywords.md -- Karved keyword database
• references/schema-templates.md -- Ready-to-use JSON-LD templates

Sub-Skills

1. seo-audit -- Full-site audit orchestrator, spawns 6 parallel agents
2. seo-technical -- Crawl/index health, HTTPS, redirects, canonical, sitemap, robots.txt
3. seo-onpage -- Title tags, meta descriptions, H1s, image alt text, internal linking
4. seo-content -- Content quality, keyword coverage, thin pages, freshness
5. seo-schema -- Structured data: Product, Organization, BreadcrumbList, FAQ
6. seo-keywords -- Keyword research, search intent mapping, opportunity scoring
7. seo-competitor -- Competitor organic rankings, content gap analysis

Agents

For parallel analysis during full audits:

• audit-technical -- Technical SEO checks (Sonnet, maxTurns: 20)
• audit-onpage -- Per-page on-page scoring (Sonnet, maxTurns: 20)
• audit-schema -- Structured data validation (Sonnet, maxTurns: 15)
• audit-content -- Content quality and keyword coverage (Sonnet, maxTurns: 20)
• audit-speed -- Core Web Vitals and image optimization (Sonnet, maxTurns: 15)
• audit-backlinks -- External link profile from GSC export (Haiku, maxTurns: 10)