seo-competitor

name	seo-competitor
description	Shopify competitor gap analysis sub-skill. Identifies content gaps by comparing store coverage against competitor organic patterns using web search. Produces a gap table — not scored findings. Uses web search — results reflect publicly indexed pages at time of run. Use when user runs /seo competitor or when seo-audit delegates competitor checks.

SEO Competitor Gap Analysis

Competitor gap analysis sub-skill for Shopify stores. Identifies keyword-level and content topic cluster gaps by comparing the store's content coverage against competitor organic patterns. Uses web search to infer what competitors target — no paid API required. This is a research companion skill — it does NOT produce PASS/FAIL findings or contribute to the SEO Health Score.

Important: Results reflect publicly indexed competitor pages at time of run — treat as directional signals, not audited inventories.

Quick Reference

Command	What it does
/seo competitor <url>	Run competitor gap analysis against a Shopify store
(via seo-audit)	Receives crawl data from parent orchestrator

Context Intake

This skill is invoked by seo-audit or directly via /seo competitor <url>.

When invoked by seo-audit:

• Store URL and crawl data path are provided by the parent — do NOT re-ask
• Read seo-audit-crawl.json from the provided path
• Proceed directly to Execution Logic

When invoked directly:

• If store URL not provided, read ~/.claude/skills/seo/profiles/karved.json and use preset
• Run python3 ~/.claude/skills/seo/scripts/crawl_store.py <url> to generate crawl data before proceeding
• Save output as seo-audit-crawl.json in the current directory
• Then proceed to Execution Logic

Execution Logic

Execute these steps in order:

1. Read seo-audit-crawl.json from the provided path (or current directory if invoked standalone)
2. Load ~/.claude/skills/seo/references/benchmarks.md — extract competitor names: Totally Promotional (totallypromotional.com), rushIMPRINT (rushimprint.com), Vistaprint (vistaprint.com)
3. Load ~/.claude/skills/seo/references/drinkware-keywords.md — extract all keywords for cross-reference
4. Build a coverage map of the store: for each page in seo-audit-crawl.json, extract title, h1, and meta_description (case-insensitive). This determines what the store already covers. If meta_description is absent from crawl data, fall back to title + H1 only and note "meta_description field not available."
5. Run up to 5 web search queries to discover competitor content patterns:

#	Query	Purpose
1	site:totallypromotional.com custom tumblers	Discover Totally Promotional's indexed tumbler pages and keyword targeting
2	site:rushimprint.com drinkware	Discover rushIMPRINT's drinkware category pages
3	"promotional drinkware" site:vistaprint.com	Discover Vistaprint's drinkware content coverage
4	totallypromotional.com corporate gifts drinkware	Content topic cluster discovery (broader results including guides/blogs)
5	rushimprint.com "bulk order" tumblers guide	Content depth discovery (FAQ, guide, comparison pages)

6. From web search results, identify two types of gaps:

   Keyword-Level Gaps: Keywords from drinkware-keywords.md that appear in competitor search results (competitor page titles, snippets, or URLs) but are absent from the store's crawl data coverage map (not found in any page's title, h1, or meta_description via case-insensitive substring match).

   Content Topic Cluster Gaps: Content categories that competitors have but the store lacks. Infer these from competitor page titles, URLs, and snippets in the search results. Examples: "corporate gifting guide", "bulk order FAQ", "how UV printing works", "design template library", "size comparison guide for tumblers". These are content types, not individual keywords.

7. Assign Priority based on how many of the 3 competitors cover the topic/term:

   • 3/3 competitors cover it: High priority
   • 2/3 competitors cover it: Medium priority
   • 1/3 competitor covers it: Low priority

8. Write output to seo-competitor-gaps.md in the current directory

Note: Web search results reflect publicly indexed competitor pages at time of run — treat as directional signals, not audited inventories. Competitor content changes frequently; re-run periodically for updated signals.

Output Format

Write findings to seo-competitor-gaps.md in the current directory using this format. The output file name is always seo-competitor-gaps.md.

# Competitor Content Gaps

**Store:** {store_url}
**Date:** {audit_date}
**Competitors checked:** Totally Promotional (totallypromotional.com), rushIMPRINT (rushimprint.com), Vistaprint (vistaprint.com)
**Web search queries run:** {list the queries executed}

> Results reflect publicly indexed competitor pages at time of run — treat as directional signals, not audited inventories.

## Keyword-Level Gaps

Keywords from drinkware-keywords.md that competitors target but the store does not cover in title, H1, or meta description.

| Keyword / Term | Competitors Cover It | Store Covers It | Priority |
|----------------|---------------------|-----------------|----------|
| bulk custom tumblers | TP, rushIMPRINT, Vistaprint | No | High |
| corporate gifting drinkware | TP, rushIMPRINT | No | Medium |
| custom tumbler minimum order | rushIMPRINT | No | Low |

## Content Topic Cluster Gaps

Content categories that competitors have but the store lacks — inferred from competitor page structure via web search.

| Topic Cluster | Competitors Cover It | Store Covers It | Priority |
|---------------|---------------------|-----------------|----------|
| Bulk order FAQ / how bulk ordering works | TP, rushIMPRINT, Vistaprint | No | High |
| Corporate gifting guide | TP, rushIMPRINT | No | Medium |
| Design template library | rushIMPRINT | No | Low |

## Summary

**Total:** {N} keyword gaps ({X} High, {Y} Medium, {Z} Low). {M} topic cluster gaps ({A} High, {B} Medium, {C} Low).

> Coverage check: keyword appears in title, H1, or meta description of any store page (case-insensitive substring match).
> Priority based on number of competitors covering the topic: 3/3 = High, 2/3 = Medium, 1/3 = Low.

IMPORTANT: Do NOT include a score line. This is a research companion skill that surfaces gaps — it does not produce scored findings and does not contribute to the SEO Health Score. The output file seo-competitor-gaps.md is consumed by seo-audit Step 7 for the Opportunities section only.

Quality Gates

This skill inherits quality gates from seo/SKILL.md by reference. No quality gate enforcement is needed — this skill produces gap tables, not PASS/WARNING/FAIL findings. The quality gates apply to audit skills only.

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/benchmarks.md — Required: competitor names (Totally Promotional, rushIMPRINT, Vistaprint) and organic CTR benchmarks for context
• references/drinkware-keywords.md — Required: keyword list for cross-reference against competitor coverage. Section membership indicates keyword tier for prioritization context.