# SEO Audit

> Full Shopify SEO audit with parallel subagent delegation. Spawns 6 audit agents (technical, onpage, schema, content, speed, backlinks), aggregates results into a scored SEO-AUDIT-REPORT.md. Use when user says "seo audit", "full seo check", or "/seo audit <url>".

- Skill: `karvedconcepts/seo-audit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add karvedconcepts/seo-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/karvedconcepts/seo-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: karvedconcepts (https://skillmd.com/u/karvedconcepts)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/karvedconcepts/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

| Command | What it does |
|---------|-------------|
| `/seo audit <url>` | Full Shopify SEO audit — runs all checks, produces scored report |
| `/seo audit` | Full audit using Karved Concepts preset (karvedconcepts.com) |

## 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

```bash
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`:

| Agent | Category | Weight | Output File |
|-------|----------|--------|-------------|
| audit-technical | Technical | 25% | seo-technical-findings.md |
| audit-onpage | On-Page | 25% | seo-onpage-findings.md |
| audit-content | Content | 20% | seo-content-findings.md |
| audit-schema | Schema | 15% | seo-schema-findings.md |
| audit-speed | Speed | 15% | seo-speed-findings.md |
| audit-backlinks | Backlinks | 0% (informational) | seo-backlinks-findings.md |

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

| Sub-Skill | Output File |
|-----------|-------------|
| seo-keywords | seo-keywords-opportunities.md |
| seo-competitor | seo-competitor-gaps.md |

**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)