SEO Audit

SEO Audit

Full-site Shopify SEO audit orchestrator. Spawns 6 audit agents and 2 research sub-skills in parallel, aggregates scored results into a final SEO Health Score, and writes three output files.

Quick Reference

Context Intake

This skill is invoked by the seo orchestrator or directly via /seo audit <url>.

When invoked by seo orchestrator:

• Store URL, industry, and scope are provided by the parent — do NOT re-ask
• Proceed directly to Orchestration Logic step 2

When invoked directly:

• If store URL not provided, read ~/.claude/skills/seo/profiles/karved.json and use preset
• If store URL is provided but no industry, ask for industry type before proceeding
• Always confirm context before running the crawl

Orchestration Logic

Execute these steps in order:

Step 1: Confirm Context

Verify that store URL and industry type are available from the parent seo/SKILL.md context intake. If invoked directly, collect context per the Context Intake section above.

Step 2: Run Crawl

python3 ~/.claude/skills/seo/scripts/crawl_store.py <store_url>

Output: seo-audit-crawl.json saved to the current working directory.

This file contains per-page data (title, meta description, H1, canonical, alt texts, internal links, structured data) for all crawled pages. All sub-skills read this same file — do NOT re-crawl.

Step 3: Spawn Audit Agents (Parallel)

Launch all 6 audit agents in parallel via Task tool, passing each the store URL and the path to seo-audit-crawl.json:

Additionally, spawn research companions as sub-skills (unchanged — these are NOT agents):

Note: seo-keywords and seo-competitor produce opportunity/gap tables, NOT findings tables with PASS/WARNING/FAIL. Their output files are consumed by Step 6 for the Opportunities section only — they do not contribute to the SEO Health Score.

Each agent writes a structured findings file in this exact format:

| Check | Severity | Result | Pages Affected | Fix |

Plus a score line: **Category score: {N}/100 (Grade {X})** (Exception: audit-backlinks uses **Backlinks assessment: {summary}** — no numeric score)

Step 4: Wait for All Results

Wait for all 8 parallel tasks (6 agents + 2 sub-skills) to complete. Collect all findings files from the current working directory.

Handling missing findings files:

• If seo-content-findings.md or seo-schema-findings.md is absent (Phase 6 sub-skills not yet built), mark that category as "Pending" in the report
• Do NOT score absent categories as 0 — exclude them from the weighted average
• Adjust the denominator: redistribute weights proportionally across available categories
• Note in the report footer: "Categories marked Pending will be scored when the corresponding sub-skill is installed"
• If seo-keywords-opportunities.md or seo-competitor-gaps.md is absent: these are research companion outputs, not scored findings. Omit the corresponding Opportunities subsection in SEO-ACTION-PLAN.md with a note (see Step 6). Do NOT affect the weighted score calculation.

Step 5: Compute SEO Health Score

Load ~/.claude/skills/seo/references/scoring-system.md and apply the weighted formula:

S_total = Sum(C_pass x W_sev x W_cat) / Sum(C_total x W_sev x W_cat) x 100

Where:

• C_pass = check result: PASS = 1.0, WARNING = 0.5, FAIL = 0.0
• W_sev = severity multiplier: Critical = 5.0, High = 3.0, Medium = 1.5, Low = 0.5
• W_cat = category weight: Technical = 0.25, On-Page = 0.25, Content = 0.20, Schema = 0.15, Speed = 0.15

Recompute all category scores from the raw check data in the findings tables — do NOT parse the agent score lines. The agent score lines are for human readability; the orchestrator computes from scratch for accuracy.

Assign a grade using the Grading Thresholds:

• A: 90-100 (Excellent)
• B: 75-89 (Good)
• C: 60-74 (Needs work)
• D: 40-59 (Poor)
• F: 0-39 (Failing)

Step 6: Write Output Files

Write three files to the current working directory:

1. SEO-AUDIT-REPORT.md

• Header: store URL, audit date, overall SEO Health Score and grade
• Per-category section: category name, category score/grade, full findings table from that agent
• Footer: scoring methodology note, list of any pending categories

2. SEO-ACTION-PLAN.md

• All findings from all categories merged into one list
• Sorted by severity: Critical first, then High, Medium, Low
• Each item: check name, severity, current result, affected pages, fix recommendation
• Group by severity level with clear headers

3. SEO-QUICK-WINS.md

• Filter: only Critical and High severity findings where estimated remediation time is 15 minutes or less
• Sorted by impact: W_sev x estimated_impact descending
• Each item: what to fix, why it matters, exact steps to fix, estimated time
• If no Quick Wins found, write: "No Quick Wins identified — all Critical/High issues require more than 15 minutes to remediate."

Opportunities Section in SEO-ACTION-PLAN.md:

After the severity-grouped findings sections (Critical, High, Medium, Low), append an Opportunities section:

## Opportunities

> Research signals from seo-keywords and seo-competitor. Do not affect the SEO Health Score.

### Keyword Gaps (High difficulty only — see seo-keywords-opportunities.md for full list)
| Keyword | Intent | Recommended Page |
|---------|--------|-----------------|

### Competitor Gaps (High priority — see seo-competitor-gaps.md for full list)
| Topic/Term | Competitors Cover It | Recommended Action |
|------------|---------------------|-------------------|

Handling missing opportunity files:

• If seo-keywords-opportunities.md is absent: omit "Keyword Gaps" subsection, add note: "seo-keywords not run — keyword opportunity data not available."
• If seo-competitor-gaps.md is absent: omit "Competitor Gaps" subsection, add note: "seo-competitor not run — competitor gap data not available."
• If both files are absent: omit the entire Opportunities section.

Quality Gates

This skill inherits all quality gates from seo/SKILL.md. Do NOT redefine or soften them here. Load ~/.claude/skills/seo/SKILL.md and apply its Quality Gates section to all findings before scoring.

Key inherited gates (for reference, not redefinition):

• Duplicate title tags = Critical
• Missing canonical on duplicate content = Critical
• Missing H1 = Critical
• Non-HTTPS URLs = Critical
• Broken internal links = Critical

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, severity multipliers, category weights, grade thresholds, Quick Wins logic
• references/benchmarks.md — Industry benchmarks for scoring context (load when computing scores)
• references/shopify-seo.md — Shopify-specific SEO patterns (load when interpreting findings)