View Categories

Skill: SEO Audit

This skill produces a comprehensive SEO audit report as a Word document for a user-provided website URL. The report covers six core sections: on-page crawl audit, keyword research, competitor analysis, AI search visibility, strategy guide, and 2026 growth recommendations.

When to use this skill

Trigger when the user provides a URL and asks for any form of SEO analysis, ranking advice, or traffic improvement help. Run the full report unless the user explicitly requests a single section.

Workflow (run these phases in order)

Phase 0 — Setup

  1. Confirm the URL with the user if it’s ambiguous (e.g., they wrote “mysite.com” — confirm https:// and www. vs apex). Confirm the business type, location, and primary services/products if not obvious from the URL — this is essential for keyword research and competitor analysis. Ask in a single message, don’t bombard them.
  2. Optional API keys: If the user wants precise keyword data, they can provide a DataForSEO, Semrush, or Ahrefs API key. Otherwise, the skill uses web research to produce estimated keyword metrics, clearly labeled as estimates. Do not block on this — proceed with estimates if no key is provided.
  3. Create a working directory at /home/claude/seo-audit-work/ and stage all intermediate findings there as JSON files. The final Word doc reads from these.

Phase 1 — Site crawl & on-page audit

Read references/crawl-audit.md for the full crawl protocol and scoring rubric. In short:

  1. Fetch the homepage with web_fetch. Extract title, meta description, headings, schema, canonical, hreflang, robots directives, OG/Twitter tags, internal links.
  2. Discover more pages: try /sitemap.xml, /robots.txt, and follow internal links found on the homepage. Cap the crawl at 25 pages by default (the user can override).
  3. For each page, score against the rubric in references/crawl-audit.md and record specific, actionable fixes (not vague advice — exact items like “Title tag is 78 characters; shorten to under 60. Suggested: ‘…'”).
  4. Save findings to /home/claude/seo-audit-work/crawl.json.

Phase 2 — Keyword research

Read references/keyword-research.md. The skill supports four data sources, in this preference order:

  1. Google Keyword Planner CSV (zero API setup, gold-standard data) — if the user uploads a Keyword Planner export, use scripts/csv_keywords.py to parse it. Always offer this option first — most users have or can quickly create a Google Ads account.
  2. Google Ads API (gold-standard data, one-time OAuth setup) — if ~/google-ads.yaml exists or env vars are set, use scripts/google_ads_keywords.py.
  3. DataForSEO API (paid third-party, sources from Keyword Planner) — if DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD env vars are set, use scripts/keyword_data.py.
  4. Estimated (free, less precise) — fall back to web research-derived estimates if no real data source is available. Always label these “Est.” in the report.

Workflow:

  • At the start of Phase 2, briefly ask the user which source they want to use. CSV upload is fastest if they have or can create a Google Ads account. Don’t block on this — if they don’t respond or want to proceed quickly, fall back to estimates.
  • From the site content and business context, identify the topical cluster and seed terms.
  • Use web_search to find what real users search for (autocomplete patterns, “people also ask”, related searches).
  • Run the appropriate keyword script (or do estimates).
  • Produce 20 target keywords with: keyword, search intent (informational/commercial/transactional/navigational), monthly volume, CPC (USD), keyword difficulty (0–100), paid difficulty (0–100), rationale.
  • Save to /home/claude/seo-audit-work/keywords.json.

Note on KD (Keyword Difficulty): Google’s data gives volume, CPC, and competition (paid-auction proxy for PD), but does NOT give organic KD directly. For KD, estimate from SERP analysis (see keyword-research.md) regardless of which volume/CPC source is used. Label KD as “Est.” in the report even when volume/CPC come from Google.

Phase 3 — Competitor analysis

Read references/competitor-analysis.md. In short:

  1. Identify 3–5 competitors via web search using the target keywords from Phase 2. Prefer competitors that consistently rank in the top 10 for the user’s target terms.
  2. For each competitor, run the same on-page audit Phase 1 used on their homepage and 1–2 key pages.
  3. Build a side-by-side comparison table: site speed signals, content depth, schema usage, backlink hints (visible mentions, press), unique offerings, content cadence.
  4. Surface specific things competitors do that the user’s site doesn’t — be concrete: “Competitor A has a 3,400-word guide on X with FAQ schema; your equivalent page is 600 words with no schema.”
  5. Save to /home/claude/seo-audit-work/competitors.json.

Phase 4 — AI search visibility

Read references/ai-visibility.md. In short:

  1. Claude (this assistant): directly test by asking Claude (in the report-generation flow) several natural queries a customer would ask. Note whether the user’s site is mentioned, and if so, how.
  2. ChatGPT, Perplexity, Grok: cannot be queried directly from this environment. Generate a set of 5–10 ready-to-run prompts the user can paste into each AI, plus a scoring template. Include these in the report as an appendix.
  3. Use web_search for “site:perplexity.ai [user’s brand]” and similar to find any public traces of the brand in AI answer ecosystems.
  4. Save to /home/claude/seo-audit-work/ai-visibility.json.

Phase 5 — Strategy guide

Read references/strategy-guide.md. Synthesize Phases 1–4 into:

  1. 30-day quick wins: highest-impact fixes that take under a few hours each (meta tags, schema, GBP claim, etc.)
  2. 90-day plan: content gaps to fill, technical fixes that take longer, link-building outreach.
  3. 6-month roadmap: pillar pages, topic clusters, ongoing content cadence, AI-optimization tactics.

Each item must be a concrete next action, not a category. “Add FAQ schema to /pricing” not “improve schema.”

Phase 6 — 2026 growth playbook

Read references/growth-2026.md. Cover:

  1. Directory listings relevant to the user’s vertical and location (top general + niche-specific).
  2. Google Business Profile setup/optimization checklist.
  3. AI search optimization (GEO/AEO) — answer engine optimization patterns for 2026.
  4. Schema.org patterns that drive rich results in 2026.
  5. Programmatic & topical authority moves.
  6. Off-the-wall ideas tailored to the business: niche communities, partnerships, podcast guesting targets, etc.

Phase 7 — Generate the Word document

Run scripts/generate_report.py with the path to /home/claude/seo-audit-work/. The script reads all the JSON files, plus any narrative passages you’ve staged as markdown in /home/claude/seo-audit-work/narratives/, and produces a polished, multi-section Word document at /mnt/user-data/outputs/seo-audit-<domain>-<date>.docx.

If you need to adjust the document structure, edit the script directly — it’s a normal docx-js generator.

Finally, call present_files on the generated docx so the user can download it.

Important behaviors

  • Be specific, not generic. “Add a meta description” is bad. “Add a meta description to /services/web-design. Suggested: ‘Custom web design in Denver from $X. Mobile-first, SEO-ready sites delivered in 4 weeks. Free consult.’ (157 chars)” is good.
  • Show your work on estimates. If keyword volume is estimated, say so and explain the basis (e.g., “estimated from related-keyword research and SERP analysis; recommend validating with Semrush/Ahrefs”).
  • Don’t fabricate data. If you can’t determine something (e.g., backlink count without an API), say so plainly and suggest how the user can find it.
  • Cite sources for any factual claims pulled from the web.
  • Respect robots.txt during the crawl — if a page is disallowed, skip it and note this in the audit.
  • Token efficiency: cap web_fetch text content at ~5k tokens per page; you don’t need full HTML to audit SEO basics.

Reference files

  • references/crawl-audit.md — scoring rubric and on-page checklist
  • references/keyword-research.md — keyword methodology and intent classification
  • references/competitor-analysis.md — competitor identification and comparison template
  • references/ai-visibility.md — AI search testing protocol and prompt templates
  • references/strategy-guide.md — 30/90/180-day planning framework
  • references/growth-2026.md — directories, GBP, GEO, and 2026 tactics

Scripts

  • scripts/generate_report.py — Orchestrates docx generation from staged JSON
  • scripts/build_docx.js — The actual docx-js builder (called by generate_report.py)
  • scripts/csv_keywords.py — Parse a Google Keyword Planner CSV export (zero-setup path; preferred when the user can do a one-time export)
  • scripts/google_ads_keywords.py — Pull live data from Google Ads Keyword Planner API (requires OAuth + developer token; gold standard)
  • scripts/keyword_data.py — Pull data from DataForSEO API (paid third-party that sources from Keyword Planner)
Claude
What are your Feelings
Scroll to Top