SEO Content Audit

Phase 0: Grounding

Read ${CLAUDE_PLUGIN_ROOT}/references/grounding.md and load any _grounding/ folder it finds. Client documentation outranks every default in this skill, and any claim rules it contains bind the output. Name the loaded files at the top of what you produce.

Grounding supplies target markets and languages, which decide whether hreflang and localized metadata are findings or non-issues.

Also read ${CLAUDE_PLUGIN_ROOT}/references/output-location.md. Normalize the target URL to its exact non-www domain and resolve today's output path now:

python "${CLAUDE_PLUGIN_ROOT}/scripts/resolve_audit_output.py" --purpose SEO-AUDIT --scope <domain> --extension md

Use python3 on macOS/Linux. The Output Format section below writes to the exact returned output_path, not into the bare working directory.

Then resolve optional report metadata from the same working directory:

python "${CLAUDE_PLUGIN_ROOT}/scripts/resolve_report_metadata.py" --toolkit "Market Context Kit" --host <exact active host> --provider <exact active LLM provider> --model <exact active model id>

Never guess a runtime value. Handle the three outcomes exactly as ${CLAUDE_PLUGIN_ROOT}/references/output-location.md specifies: null means write no metadata block at all, a JSON object means reproduce its fields verbatim as YAML front matter at the very top of the report, and an error means stop rather than invent or drop attribution.

Read ${CLAUDE_PLUGIN_ROOT}/references/webfetch-artifacts.md before quoting page copy or asserting anything about a page's structure, staleness, or absence. Page text used as evidence must come from scripts/analyze_page.py or another real parser — never an ad-hoc regex HTML-to-text script — and must be text a visitor actually sees, not commented-out, hidden, or attribute-only markup.

Read ${CLAUDE_PLUGIN_ROOT}/references/google-search-guidance.md. Its Myth Guardrail binds every recommendation this audit emits, Grounding Precedence governs a myth check a grounding criterion asks for anyway, and Schema Scoring sets how Step 8 is scored.

Read ${CLAUDE_PLUGIN_ROOT}/references/search-context-integration.md. Resolve a SEARCH-CONTEXT.v1.json only from an explicit user path, or from exactly one match in the active audit folder's flat data/ for the exact domain and, if requested, the exact reporting period, then validate schema, domain, reporting period, and source statuses before reading values.

Skill Purpose

Perform a comprehensive SEO audit of a webpage or website, covering on-page SEO, content quality (E-E-A-T), keyword analysis, technical SEO, and content strategy. This skill combines automated analysis via scripts/analyze_page.py with expert-level manual review to produce an actionable SEO audit document.

When to Use

• User provides a URL and asks for SEO analysis, audit, or recommendations
• User wants to improve organic search rankings and traffic
• User asks about on-page SEO, meta tags, content quality, or technical SEO
• User wants a content gap analysis or content strategy recommendations
• Triggered by /marketkit:seo <url> or /marketkit:seo

How to Execute

Step 1: Run Automated Analysis

Use the bundled Python analysis script to gather baseline data:

# macOS / Linux
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/analyze_page.py" "<url>"
# Windows
python "${CLAUDE_PLUGIN_ROOT}/scripts/analyze_page.py" "<url>"

${CLAUDE_PLUGIN_ROOT} resolves to this plugin's directory on any machine — never hardcode a path. Use python3 on macOS and Linux, python on Windows; do not try python3 first on Windows, where it resolves to the Microsoft Store alias stub and opens the Store instead of failing cleanly.

If the output is a {"usage": ...} banner, the URL argument did not arrive — re-run with the URL quoted.

This script extracts:

• Title tag and meta description
• Open Graph tags
• Heading hierarchy (H1-H6)
• Links (internal and external)
• Images and alt text status
• Forms and CTAs
• Schema/structured data
• Social links

Step 1.5: Apply optional measured Search Context

If a valid artifact was resolved in Phase 0, use its measured queries, landing-page paths, CTR, average position, and indexing states to prioritize recommendations. Name the artifact reporting period and providers, disclose partial sources, and reject domain mismatches. Keep live HTML and the bundled analyzer as the source for structural claims; analytics evidence cannot prove a title, heading, canonical, schema, or link exists now. Do not change the SEO health score solely because of Search Context data—use it for priority and confidence.

• Tracking scripts
• Viewport meta tag (mobile-friendliness indicator)
• Canonical tag
• Robots meta directives

Capture the JSON output and use it as the foundation for the manual analysis.

Evidence and Validation Requirements

Treat script output as a starting point, not final proof. Before writing the audit:

1. Add a concise evidence table for all major findings:

2. Re-check every critical finding with direct HTML inspection or a second sampled URL before including it in the audit.
3. Do not make sitewide claims from a homepage-only sample. For schema, titles, breadcrumbs, CTAs, and indexability, sample the relevant page type first (homepage, category/listing, product/detail, article/resource).
4. If a finding cannot be externally verified, label it as "not externally verifiable" or "not verified" instead of "missing" or "not configured". For example, public HTML cannot prove whether Google Search Console is configured.

Step 2: On-Page SEO Checklist

Evaluate each element and score it as Pass, Needs Work, or Fail.

Title Tag

Common title tag mistakes:

• Too long (truncated in search results)
• Missing primary keyword
• Keyword stuffing ("Best SEO Tool | Top SEO Tool | SEO Software | SEO Platform")
• Using the same title across multiple pages
• Generic titles ("Home", "Welcome", "Page 1")
• Missing brand name

Meta Description

Heading Hierarchy (H1-H6)

Image Optimization

Internal Linking

URL Structure

Step 3: Content Quality Assessment (E-E-A-T)

Evaluate the content against Google's E-E-A-T framework:

Experience

Does the content demonstrate first-hand experience with the topic?

Check for:

• Personal anecdotes, case studies, or real-world examples
• Screenshots, photos, or evidence of hands-on experience
• Specific details that only someone with experience would know
• "I did X and here's what happened" type content

Score: Strong / Present / Weak / Missing

Expertise

Does the author have demonstrated knowledge in this subject?

Check for:

• Author bio with relevant credentials
• Depth of content (not superficial)
• Accurate information and data
• Proper use of industry terminology
• Links to authoritative sources

Score: Strong / Present / Weak / Missing

Authoritativeness

Is the website and author recognized as an authority on this topic?

Check for:

• Author bylines with real names and bios
• About page with company background
• Industry awards or certifications
• Backlinks from authoritative sites
• Media mentions or press coverage
• Guest posts on industry publications

Score: Strong / Present / Weak / Missing

Trustworthiness

Can users trust this content and this website?

Check for:

• HTTPS (SSL certificate)
• Privacy policy and terms of service
• Physical address and contact information
• Customer reviews and testimonials
• Security badges and certifications
• Transparent business practices
• Accurate, up-to-date information
• Properly sourced claims and statistics

Score: Strong / Present / Weak / Missing

Who / How / Why

Google's helpful-content guidance asks three questions of every page. Score each Pass / Needs Work / Fail:

Search-engine-first red flags

Each is a Fail for the page's helpfulness on its own, whatever the four dimensions above scored:

• Content mass-produced across topics the site has no expertise in
• Publication or update dates changed without the content changing
• Automation or AI generation used at scale and left undisclosed
• Page restates what other sources already said and adds nothing
• Topic chosen because it trends, not because the site can cover it

Step 4: Keyword Analysis

Primary Keyword Assessment

Secondary Keywords

Identify 5-10 related keywords that should be naturally included in the content:

• Synonyms and variations of the primary keyword
• Long-tail variations
• Related questions (People Also Ask)
• LSI (Latent Semantic Indexing) keywords

Search Intent Analysis

Determine the search intent behind the target keyword and evaluate if the content matches:

Misalignment is a ranking killer. If the user searches "how to do X" (informational) and lands on a sales page (transactional), they bounce -- and Google notices.

Step 5: Technical SEO Quick Check

Robots.txt

Check: Does /robots.txt exist and is it properly configured?

• robots.txt is accessible
• Not blocking important pages or resources
• Points to sitemap.xml
• Not blocking CSS/JS (needed for rendering)

XML Sitemap

Check: Does /sitemap.xml exist?

• Sitemap exists and is accessible
• Contains all important pages
• No broken URLs in sitemap
• Submitted to Google Search Console
• Last modified dates are accurate

Canonical Tags

• Canonical tag present on the page
• Points to the correct URL (self-referencing or to the canonical version)
• Consistent with robots.txt and sitemap

Page Speed

Reference benchmarks:

Common speed issues to flag:

• Unoptimized images (recommend WebP format, compression)
• Render-blocking JavaScript or CSS
• No browser caching headers
• No CDN detected
• Excessive third-party scripts (tracking, widgets, fonts)
• Unminified CSS and JavaScript
• Missing compression (gzip or brotli)

Mobile-Friendliness

• Viewport meta tag present (<meta name="viewport" content="width=device-width, initial-scale=1">)
• Text readable without zooming (minimum 16px body text)
• Tap targets adequately sized and spaced (minimum 48x48px)
• No horizontal scrolling required
• Responsive images
• Forms usable on mobile

Step 6: Content Gap Analysis

Methodology for identifying content gaps:

1. Identify the topic cluster: What is the main topic this page/site covers?
2. Map existing content: What subtopics are already covered?
3. Identify missing subtopics: What related topics are competitors covering that this site is not?
4. Analyze People Also Ask: What questions do searchers have about this topic?
5. Check related searches: What does Google suggest at the bottom of the SERP?

Content Gap Template:

Step 7: Featured Snippet Optimization

Identify opportunities to capture featured snippets:

Types of featured snippets:

1. Paragraph snippet -- Answer in 40-60 words. Use a clear question as H2/H3 followed by a concise answer.
2. List snippet -- Use ordered or unordered lists with H2 containing the target query.
3. Table snippet -- Use HTML tables with clear headers.
4. Video snippet -- Include video with descriptive title and timestamps.

Optimization checklist:

• Target question-based queries ("how to", "what is", "why does")
• Place answer immediately after the question heading
• Keep paragraph answers between 40-60 words
• Use structured lists and tables where appropriate
• Include the target query in an H2 or H3

Step 8: Schema Markup Audit

Check for structured data implementation:

Implementation guidance:

• Use JSON-LD format (Google's preferred format)
• Validate with Google's Rich Results Test
• Don't mark up content that isn't visible on the page
• Keep schema data consistent with on-page content
• Recommend schema for what it actually buys: rich-result eligibility, entity clarity via Organization + sameAs, Merchant Center feeds, machine-readable facts. It is not a ranking factor, and Google states no schema.org markup is required for generative AI search — never justify a schema recommendation by AI visibility
• A page type with no eligible rich-result type is not a gap for lacking schema. Score per Schema Scoring in ${CLAUDE_PLUGIN_ROOT}/references/google-search-guidance.md, and resolve currently eligible types from Google's search gallery rather than treating the table above as complete

Step 9: Internal Linking Opportunities

Identify specific internal linking improvements:

1. Orphan pages -- Pages with no internal links pointing to them
2. Hub pages -- High-authority pages that should link to related content
3. Topical clusters -- Group related content and create linking structures
4. CTA links -- Blog content should link to relevant product/service pages
5. Footer/sidebar links -- Sitewide links to important pages

Linking Architecture Assessment:

Homepage
  |-- Category/Service Pages (Pillar Content)
       |-- Individual Blog Posts/Articles (Cluster Content)
            |-- Back-links to Pillar Content
  |-- Key Conversion Pages (Pricing, Signup, Contact)
       |-- Linked from relevant content

Step 10: Core Web Vitals Impact Assessment

Evaluate the revenue impact of Core Web Vitals performance:

Research-backed impacts:

• Sites passing all Core Web Vitals see 24% fewer page abandonments
• A 100ms decrease in LCP correlates with a 1.1% increase in conversion rates
• Reducing CLS by 0.1 corresponds to a 15% decrease in bounce rate
• Pages loading within 2 seconds have an average bounce rate of 9%, while pages loading in 5 seconds have a 38% bounce rate

Recommendations by metric:

Step 11: Blog and Content Strategy Recommendations

Based on the audit findings, recommend:

1. Publishing cadence -- How often to publish based on competition and resources
2. Content types -- Blog posts, guides, tools, videos, infographics
3. Keyword targeting strategy -- Balance between high-volume and long-tail
4. Content length -- Benchmark against top-ranking content for target keywords
5. Content update strategy -- How often to refresh existing content
6. Distribution plan -- How to promote content beyond organic search

Content Prioritization Matrix:

Scoring: High volume + Low competition + High business value = Highest priority

Step 12: Filter Myth Recommendations

Before writing Prioritized Recommendations, filter every recommendation against the Myth Guardrail in ${CLAUDE_PLUGIN_ROOT}/references/google-search-guidance.md. A match is dropped, not downgraded. Where grounding asked for one of those checks, report the finding as a fact under Technical SEO with its evidence — never as a Critical, High, Medium, or Low recommendation.

Output Format: MARKETKIT - SEO-AUDIT - <domain>.md

Write the exact output_path resolved in Phase 0 (${CLAUDE_PLUGIN_ROOT}/references/output-location.md) with:

[YAML front matter from the Phase 0 metadata resolver — exact shape in references/output-location.md. Omit the whole block when the resolver returned null.]

# SEO Content Audit

## [URL]

### Date: [Date]

### Optional data source: [SEARCH-CONTEXT.v1.json path, reporting period, source statuses — or: not used]

---

## SEO Health Score: [X/100]

---

## On-Page SEO Checklist

### Title Tag

- Status: [Pass/Needs Work/Fail]
- Current: "[current title]"
- Recommended: "[improved title]"
- Issues: [list issues]

### Meta Description

- Status: [Pass/Needs Work/Fail]
- Current: "[current meta]"
- Recommended: "[improved meta]"

### Heading Hierarchy

[H1-H6 structure analysis]

### Image Optimization

[Alt text audit results]

### Internal Linking

[Link analysis]

### URL Structure

[URL assessment]

---

## Content Quality (E-E-A-T)

| Dimension         | Score                         | Evidence  |
| ----------------- | ----------------------------- | --------- |
| Experience        | [Strong/Present/Weak/Missing] | [details] |
| Expertise         | [Strong/Present/Weak/Missing] | [details] |
| Authoritativeness | [Strong/Present/Weak/Missing] | [details] |
| Trustworthiness   | [Strong/Present/Weak/Missing] | [details] |

---

## Keyword Analysis

- Primary Keyword: [keyword]
- Search Intent: [type]
- Keyword Placement: [checklist results]
- Secondary Keywords: [list]

---

## Technical SEO

[Quick check results]

---

## Content Gap Analysis

[Missing topics table]

---

## Featured Snippet Opportunities

[Specific opportunities]

---

## Schema Markup

[Current vs recommended]

---

## Internal Linking Opportunities

[Specific recommendations]

---

## Core Web Vitals

[Performance assessment with revenue impact]

---

## Content Strategy Recommendations

[Publishing plan, content priorities]

---

## Prioritized Recommendations

### Critical (Fix Immediately)

1. [recommendation with expected impact]

### High Priority (This Month)

1. [recommendation]

### Medium Priority (This Quarter)

1. [recommendation]

### Low Priority (When Resources Allow)

1. [recommendation]

Key Principles

• SEO audits should be educational, not just diagnostic. Explain WHY each element matters so the client understands the value.
• Always provide the "before" (current state) and "after" (recommended change) so the client can see exactly what needs to change.
• Tie SEO improvements to business outcomes. "Optimizing your title tag" means nothing to a business owner. "Optimizing your title tag could increase your click-through rate by 20-35%, bringing an estimated 500 more visitors per month to this page" is actionable.
• Use the automated script data as a starting point, but add expert analysis on top. The script finds the data; the skill interprets what it means.
• Prioritize recommendations by effort-to-impact ratio. A title tag change takes 5 minutes but can impact every search impression. A full content rewrite takes weeks.
• If the user has run /marketkit:audit or /marketkit:landing previously, cross-reference those findings with the SEO audit for a more complete picture.