SEO Auditor

Performs a comprehensive SEO audit across three dimensions: technical SEO (crawlability, site speed, mobile-friendliness, indexation), on-page SEO (titles, meta descriptions, headings, content quality, keyword usage), and off-page SEO (backlink profile, domain authority, brand mentions). Uses WebSearch and browser automation to gather live data. Returns a prioritized fix list with impact scores and estimated effort for each recommendation.

Prerequisites

WebSearch tool available for SERP analysis and external data gathering
Browser automation tool available for crawling target site pages
Target website URL
Optional: agency.config.json for service-specific audit focus and client context

Capabilities Used

content-seo-optimizer -- for detailed on-page analysis of individual pages
schema-generator -- for structured data gap identification

Phase 0: Intake

Read agency.config.json from the project root (if available).
Extract services[] to understand which SEO areas the agency can deliver on.
Extract icp.segments[] to contextualize recommendations for the client's market.
Accept parameters:
- url -- (required) the website to audit
- depth -- quick (homepage + one inner page) | standard (homepage + 5 key pages) | deep (full site crawl, up to 50 pages). Default: standard
- focus -- (optional) specific area: technical, on-page, off-page, or all. Default: all
- competitor_urls -- (optional) array of competitor URLs for comparative analysis

Phase 1: Technical SEO Audit

Crawlability and Indexation

Check robots.txt at {{url}}/robots.txt -- parse directives, identify blocked paths
Check sitemap.xml at {{url}}/sitemap.xml -- verify existence, validate format, count URLs
WebSearch: site:{{domain}} -- compare indexed page count against sitemap URLs
Check for canonical tags on sampled pages -- identify self-referencing and cross-domain canonicals
Check for noindex, nofollow meta tags on pages that should be indexed
Look for orphan pages (in sitemap but not linked from navigation)

Site Speed

WebSearch: "{{domain}}" pagespeed OR "page speed" OR "core web vitals"
Check visible indicators: image optimization (WebP/AVIF usage, lazy loading), font loading strategy, render-blocking resources
Note any visible layout shifts (CLS indicators)
Check for excessive JavaScript bundle size indicators (slow interactivity)
Mobile speed: test primary pages on mobile viewport

Mobile-Friendliness

Visit site on mobile viewport via browser automation
Check responsive layout, touch target sizes, font readability
Verify mobile menu functionality
Check for horizontal scroll issues
Verify viewport meta tag is set correctly

URL Structure and Architecture

Evaluate URL patterns: clean, descriptive, consistent hierarchy
Check for URL parameters creating duplicate content
Verify HTTPS across all pages (mixed content warnings)
Check redirect chains (301/302 hops)
Evaluate internal linking depth (clicks from homepage to deepest content)

International SEO (if applicable)

Check for hreflang tags
Verify language/region targeting
Check for proper locale-specific URLs

Phase 2: On-Page SEO Audit

For each sampled page, evaluate:

Title Tags

Present and unique per page
Length: 50-60 characters optimal
Primary keyword placement (front-loaded)
Brand name inclusion pattern
Compelling for click-through (not just keyword-stuffed)

Meta Descriptions

Present and unique per page
Length: 150-160 characters optimal
Include primary keyword naturally
Contain a call-to-action or value proposition
Compelling enough to improve CTR from SERPs

Heading Structure

Single H1 per page containing primary keyword
Logical H2/H3 hierarchy (no skipped levels)
Keywords distributed naturally across headings
Headings reflect content structure (not just styled text)

Content Quality

Word count per page (thin content < 300 words on key pages is a red flag)
Keyword density: primary keyword appears naturally (1-3% density)
Related keywords and LSI terms present
Content freshness: last updated dates, outdated references
Duplicate content: check for substantially similar pages
Internal linking: each page links to 3-5 relevant internal pages

Image Optimization

Alt text present and descriptive on all images
File names descriptive (not IMG_001.jpg)
Image file sizes reasonable (< 200KB for most images)
Next-gen formats (WebP, AVIF) in use
Responsive images with srcset attributes

Structured Data

Check for existing JSON-LD markup
Identify missing schema types (Organization, Product, FAQ, BreadcrumbList)
Validate existing schema for errors
Flag rich snippet opportunities not being captured

Phase 3: Off-Page SEO Audit

Backlink Profile

WebSearch: "{{domain}}" -site:{{domain}} -- estimate external mention volume
WebSearch: link:{{domain}} -- check for backlink indicators
WebSearch: "{{domain}}" backlinks OR "domain authority" OR "domain rating" -- find third-party reports
Identify linking domains by category: editorial, directory, social, forum, spam
Check for toxic backlink indicators (spammy anchor text, irrelevant foreign domains)

Domain Authority Signals

WebSearch: "{{domain}}" "domain authority" OR "DA" OR "domain rating" OR "DR"
Compare against competitor DA/DR if competitor URLs provided
Check domain age and registration history signals

Brand Presence

WebSearch: "{{brand_name}}" -site:{{domain}} -- find brand mentions
Check for unlinked brand mentions (link building opportunities)
Social media presence and engagement signals
Google Business Profile presence (for local businesses)
Review site presence (G2, Trustpilot, Clutch for B2B)

Competitor Comparison (if competitor URLs provided)

Compare indexed page counts
Compare visible backlink profiles
Compare content volume and freshness
Identify keywords competitors rank for that the target does not

Phase 4: SERP Analysis

Current Visibility

WebSearch: site:{{domain}} -- check indexed pages and featured results
Search for brand name -- verify knowledge panel, sitelinks
Search for primary service/product keywords -- check if domain appears in top 20
Check for featured snippet ownership on key queries

SERP Feature Opportunities

Identify queries where "People Also Ask" boxes appear -- content gap opportunities
Check for video carousel presence -- video content opportunity
Check for image pack presence -- image optimization opportunity
Local pack presence -- local SEO opportunity
Shopping results -- product feed opportunity

Phase 5: Score and Prioritize

Assign scores from 1-10 for each area:

Technical SEO: crawlability, speed, mobile, URL structure
On-Page SEO: titles, meta, headings, content, images, schema
Off-Page SEO: backlinks, DA, brand presence
Overall SEO Health: weighted average (Technical 35%, On-Page 40%, Off-Page 25%)

Scoring guide:

9-10: Excellent, minor optimizations only
7-8: Good, clear improvement areas that will compound
5-6: Average, significant gaps losing organic traffic
3-4: Below average, fundamental issues blocking growth
1-2: Critical, site is nearly invisible to search engines

Prioritize all findings by:

Impact: How much organic traffic will this fix recover/gain? (High/Medium/Low)
Effort: How long to implement? (Quick win / Medium project / Major initiative)
Urgency: Is this actively harming rankings? (Critical / Important / Nice-to-have)

Phase 6: Output

Return structured JSON:

{
  "url": "https://example.com",
  "audited_at": "2024-01-15T14:30:00Z",
  "depth": "standard",
  "pages_audited": [
    "https://example.com",
    "https://example.com/products/example",
    "https://example.com/blog/example-post"
  ],
  "overall_score": "5.8/10",
  "score_breakdown": {
    "technical_seo": "6/10",
    "on_page_seo": "5/10",
    "off_page_seo": "6/10"
  },
  "critical_issues": [
    {
      "area": "Technical",
      "issue": "No sitemap.xml found",
      "impact": "High",
      "effort": "Quick win (1 hour)",
      "urgency": "Critical",
      "fix": "Generate and submit XML sitemap via Google Search Console. Most CMS platforms auto-generate this.",
      "impact_score": 9
    }
  ],
  "high_priority": [
    {
      "area": "On-Page",
      "issue": "Missing meta descriptions on 70% of pages",
      "impact": "High",
      "effort": "Medium (4-8 hours)",
      "urgency": "Important",
      "fix": "Write unique meta descriptions for all key pages, starting with highest-traffic pages.",
      "impact_score": 8
    }
  ],
  "medium_priority": [
    {
      "area": "Off-Page",
      "issue": "12 unlinked brand mentions found",
      "impact": "Medium",
      "effort": "Medium (outreach campaign)",
      "urgency": "Nice-to-have",
      "fix": "Contact site owners to convert mentions into backlinks.",
      "impact_score": 5
    }
  ],
  "low_priority": [],
  "strengths": [
    "Clean URL structure with descriptive slugs",
    "HTTPS properly configured across all pages",
    "Good internal linking between related content"
  ],
  "quick_wins": [
    "Add sitemap.xml and submit to Search Console",
    "Fix 15 missing alt tags on homepage images",
    "Add FAQ schema to the 3 support pages"
  ],
  "competitor_comparison": {
    "indexed_pages": { "target": 120, "competitor_avg": 450 },
    "estimated_da": { "target": "25", "competitor_avg": "42" },
    "content_gap_keywords": ["keyword1", "keyword2", "keyword3"]
  },
  "next_steps": [
    "Fix critical technical issues (Week 1)",
    "Optimize on-page elements for top 10 pages (Week 2-3)",
    "Launch link building campaign for unlinked mentions (Week 4+)"
  ]
}

Phase 7: Review Gate

Present findings to the user before taking action. The user may:

Adjust scores or remove false positives
Request deeper analysis on specific areas
Select which fixes to prioritize for implementation
Request a comparison with specific competitors

Example Usage

Trigger phrases:

"Run an SEO audit on [url]"
"Check [url] for SEO issues"
"Full SEO analysis of [domain]"
"Technical SEO check on [url]"
"How is [url] doing on SEO?"

User: Run an SEO audit on https://brandx.com
Assistant: [crawls homepage and key pages, checks technical/on-page/off-page, returns scored findings with prioritized fix list]

User: Quick SEO check on example.com, focus on technical issues
Assistant: [homepage + one inner page, technical SEO only, returns critical and high-priority technical fixes]

User: Deep SEO audit of brandx.com vs competitor1.com and competitor2.com
Assistant: [full crawl up to 50 pages, all dimensions, comparative analysis against both competitors]

seo-auditor

SKILL.mdskills/composites/seo-auditor/SKILL.md