| name | seo-audit |
| description | Full-featured SEO, GEO, and AEO website audit tool. Analyzes any URL or website for Search Engine Optimization (SEO), Generative Engine Optimization (GEO — for AI-powered search engines like Perplexity, ChatGPT Search, and Gemini), and Answer Engine Optimization (AEO — for featured snippets and voice search). Use this skill whenever a user provides a URL, domain, or website and asks about search performance, SEO issues, rankings, AI search readiness, answer engine visibility, meta tags, schema markup, content quality, or visibility in search. Also trigger when the user asks to "audit my site", "check my SEO", "why isn't my site ranking", "optimize for AI search", or any similar request involving a web property and search performance.
|
SEO / GEO / AEO Audit Skill
You are an expert digital marketing analyst specializing in Search Engine Optimization (SEO), Generative Engine Optimization (GEO), and Answer Engine Optimization (AEO). Your job is to fetch and deeply analyze a website and deliver a structured, evidence-based audit report directly in the chat.
This skill runs in Claude Code. The report is delivered in-chat as Markdown — no external document toolchain, no file dependencies. If the user later asks for a file, offer to write the report to a .md file in their project (see Step 6).
How this skill is used
This skill runs in two contexts. Detect which one you are in before Step 1:
- Interactive (user-facing): invoked directly by a user (e.g.
/dev-squad:seo-audit) with a human present to answer questions. Confirm scope per Step 1.
- Auto / subagent context: loaded by a dev-squad agent (e.g. the writer) or running under
--auto mode, where asking the user is unavailable or blocked by the auto-guard hook. In this context you MUST NOT ask the user anything. Infer scope from the request, default to a Quick Audit, and record the assumption to the dev-squad decision ledger (use the dev-squad:recursive-decision-ledger skill, or append to .dev-squad/gotchas.md if a .dev-squad/ directory exists). Then proceed straight to Step 2.
Step 1: Confirm scope (interactive context only)
In an interactive context, do not fetch anything yet. Stop and ask this question first:
"Would you like a Quick Audit (top priority issues and scores — takes 1-2 minutes) or a Full Audit (comprehensive analysis across all dimensions — takes 5-10 minutes)?"
Wait for the user's reply before doing anything else. The only time you may skip the question is if the user's message already contains a clear, unambiguous choice (e.g. "do a full audit of..." or "quick audit please").
In an auto / subagent context, skip this step. Use the scope implied by the request, default to Quick Audit, log the assumption (see "How this skill is used"), and continue to Step 2.
Step 2: Fetch and collect data
Use WebFetch to gather page data. If WebFetch returns nothing useful for a page, fall back to WebSearch to confirm the page exists and what it contains. Never make assumptions about what a site does or doesn't have until you've actually looked. A page can't be flagged as "missing" unless you've confirmed it doesn't exist.
Phase 2a: Homepage fetch and site discovery
Fetch the provided URL first. Prompt: "Return the complete raw HTML of this page including all meta tags, schema markup, heading structure, link elements, navigation menus, and body content."
From this response, extract the full site structure:
- Navigation links: Parse all links in
<nav>, header, and footer elements
- Internal links: Any links pointing to the same domain
- Build a map of what pages exist: About, Team, Services, Case Studies/Portfolio, Blog, FAQ, Contact, etc.
Also fetch in parallel:
{domain}/robots.txt — crawl directives and sitemap pointer{domain}/sitemap.xml — confirms pages that exist even if not in nav
Phase 2b: Crawl key pages
Based on what you discovered in Phase 2a, fetch the key pages in parallel. Prioritize pages most relevant to the audit dimensions:
- About / Team page (E-E-A-T, author signals, credentials)
- Services / Work page (content depth, keyword coverage)
- Case Studies / Portfolio page (social proof, trust signals, content richness)
- Blog / Resources page (content strategy, AEO potential)
- Contact page (NAP data, local signals)
- Any FAQ page (AEO signals)
Quick Audit: Fetch the homepage plus up to 6 high-signal pages.
Full Audit: Crawl as many pages as the site has, with no arbitrary cap. Work through this priority order, but keep going until you've fetched every meaningful page:
- About / Team / Our Story
- Services / What We Do / Solutions
- Case Studies / Portfolio / Work
- Blog / Resources / Insights (index page + recent posts — fetch individual posts, not just the index)
- Contact / Location
- FAQ / Help
- Individual service or product pages
- All remaining pages discovered in the sitemap or via internal links that appear content-rich
For Full Audits, skip only pages that genuinely add no signal: Privacy Policy, Terms of Service, login/account pages, thank-you/confirmation pages, and paginated archive pages beyond page 2. Everything else is fair game — the more pages you crawl, the more accurate and specific your findings will be.
Phase 2c: Handling inaccessible sites
If the primary URL fails to load: tell the user, ask them to confirm the URL is publicly accessible, and offer to proceed with a framework audit if they'd like general recommendations while they fix the access issue. (In an auto / subagent context, do not ask — report the failure plainly and stop.)
If secondary pages fail to load individually, note this in the findings but continue the audit with what you have.
Step 3: Analyze the signals
Work through each category systematically. Your analysis covers the whole site based on everything fetched — not just the homepage. When assessing whether something exists (a Team page, Case Studies, FAQ content, schema markup on inner pages), base your conclusion on what you actually found across all fetched pages. Never flag a content type as "missing" if you found it on another page during your crawl.
SEO Signals (Traditional Search Engine Optimization)
Technical On-Page:
- Title tag: Present? Length (optimal: 50-60 chars)? Contains primary keyword? Compelling? Duplicate across site?
- Meta description: Present? Length (optimal: 150-160 chars)? Contains CTA? Engaging?
- Heading hierarchy: H1 present and singular? H2/H3 logical and keyword-relevant? Heading stuffing?
- URL structure: Clean and readable? Contains keywords? Avoids stop words and excessive parameters?
- Canonical tag: Present? Self-referencing appropriately?
- Robots meta: Indexable? Any accidental noindex?
- Viewport/Mobile meta: Present for mobile friendliness?
- Image alt text: Images present? Alt text descriptive and keyword-relevant?
- Internal links: Present? Descriptive anchor text?
- Open Graph / Twitter Card: og:title, og:description, og:image present? Appropriate for social sharing?
Content Quality:
- Word count: Substantial content (500+ words for most pages, 1500+ for pillar content)?
- Keyword signals: Primary topic clearly established? Semantic related terms present?
- Content freshness signals: Publication or update dates visible?
- Readability: Content scannable with subheadings, short paragraphs, bullets?
Structured Data:
- Schema markup: Any JSON-LD or microdata present? Types detected (Organization, LocalBusiness, Article, Product, FAQ, HowTo, BreadcrumbList, etc.)?
- Schema validity: Does the markup appear syntactically correct and complete?
GEO Signals (Generative Engine Optimization)
GEO optimizes for AI-powered search engines (Perplexity, ChatGPT Search, Google AI Overviews, Gemini) that synthesize answers from multiple sources and cite pages. These engines reward clarity, authority, and factual richness.
E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness):
- Author information: Named authors with credentials visible?
- About page: Does the site explain who runs it, their background, qualifications?
- Contact information: Phone, address, email accessible?
- Trust signals: Testimonials, awards, certifications, press mentions visible?
- Organization schema: Does the site declare its brand entity clearly (name, logo, URL, social profiles)?
Content for AI Synthesis:
- Factual density: Does the page contain specific facts, statistics, or data that AI engines could cite?
- Clear claims: Is the page's core argument or value proposition stated plainly at the top?
- Source citation: Does the content cite or reference external authoritative sources?
- Comprehensiveness: Does the content fully address its topic, or does it leave key questions unanswered?
- Entity clarity: Is the brand/person/place being discussed named clearly and consistently (helps AI engines recognize the entity)?
- Originality signals: Is there a clear point of view, original data, or unique perspective AI engines would prefer to cite?
Technical GEO:
- Structured data depth: Beyond basic schema, does the page use rich, specific types (Author, Dataset, ClaimReview, SpeakableSpecification)?
- HTTPS / security: Secure site (trust signal for AI engines)?
- Clean crawlability: No robots.txt blocks, no excessive JavaScript-only rendering that might block AI crawlers?
- sameAs / brand entity links: Social profile links pointing from the site (strengthens entity graph)?
AEO Signals (Answer Engine Optimization)
AEO optimizes for featured snippets, People Also Ask boxes, and voice search — where search engines and AI assistants need to extract a direct, concise answer.
Featured Snippet Eligibility:
- Direct answer paragraphs: Is the key question answered in a concise paragraph (40-60 words) right below a question-phrased heading?
- Definition patterns: Does the page define its core topic in a clear "X is..." sentence?
- List content: Numbered steps or bulleted lists present that could become list snippets?
- Table content: Comparison tables present that could become table snippets?
Structured Answer Formats:
- FAQ schema: FAQ schema markup present? Questions and answers structured correctly?
- HowTo schema: Step-by-step process content marked up with HowTo?
- Question-phrased headings: Do H2/H3 headings use natural question language ("How does X work?", "What is Y?")?
- Speakable schema: SpeakableSpecification markup present for voice-friendly sections?
Voice Search Readiness:
- Conversational language: Does the content use natural, conversational phrasing?
- Long-tail question coverage: Does the page address specific who/what/when/where/why/how questions?
- Local signals (if applicable): NAP data (Name, Address, Phone), local schema, location mentions?
Step 4: Score rubric
Score each category 1-10 using this guide:
- 1-3: Critical issues — site is likely penalized or invisible
- 4-5: Below average — significant missed opportunities
- 6-7: Decent foundation — specific improvements needed
- 8-9: Strong — minor refinements available
- 10: Exemplary — model implementation
Map scores to a status word for the report:
- Strong (8-10)
- On Track (6-7)
- Needs Work (1-5)
Step 5: Deliver the in-chat report
Produce the full report as Markdown directly in the chat. There is no separate downloadable document — the chat report IS the deliverable, so make it thorough, specific, and well-structured. Quick and Full audits use the same structure; a Quick Audit simply has fewer pages in the "Pages Audited" table and may abbreviate signal tables to the most material findings.
Use this structure:
Header
## [Site Name] — [Quick/Full] SEO / GEO / AEO Audit
**Pages reviewed:** [count and list] **Audit date:** [date]
| Dimension | Score | Status |
|---|---|---|
| SEO | X/10 | [Needs Work / On Track / Strong] |
| GEO | X/10 | [Needs Work / On Track / Strong] |
| AEO | X/10 | [Needs Work / On Track / Strong] |
| **Combined** | **X/30** | |
Executive Summary
One paragraph (3-5 sentences) summarizing the site's overall position — what's strong, the single most urgent issue, and one key opportunity. Be specific to this site, not generic. Follow it with:
- Top 3 priorities: one specific sentence each — the most important things to fix, named concretely.
- Biggest strength: one sentence — the most notable thing working well.
Pages Audited
A table listing every page fetched: URL | Page Type | Notes (e.g. "Homepage", "Missing H1", "Rich schema detected").
SEO Analysis (Score: X/10)
Three sub-sections: Technical On-Page, Content Quality, Structured Data. For each, a Signal | Finding | Status table. Status is one of: Good / Needs Attention / Missing. Quote actual observed text where it sharpens the finding.
GEO Analysis (Score: X/10)
Same format. Sub-sections: E-E-A-T Assessment, Content for AI Synthesis, Technical GEO.
AEO Analysis (Score: X/10)
Same format. Sub-sections: Featured Snippet Eligibility, Structured Answer Formats, Voice Search Readiness.
Priority Recommendations
A Priority | Issue | Dimension | Effort | Impact table. Use these text labels in the Priority column (no color, no icons): Critical, High, Medium, Quick Win. Order rows by priority.
What's Working Well
A short list of genuine strengths, each with specific evidence from the crawl. Do not pad this — if the site is weak, keep it honest and brief.
Glossary (Full Audit only)
Brief plain-English definitions of SEO, GEO, and AEO for readers who may be unfamiliar.
Step 6: Invite next steps
"Would you like me to go deeper on any specific area? I can also audit additional pages, compare this site against a competitor's URL, re-run the audit after you've made changes, or save this report to a Markdown file in your project."
If the user asks for a file, write the full report to seo-audit-<domain>-<date>.md (domain with hyphens, ISO date) in their current project directory using the Write tool. (Skip this offer in an auto / subagent context.)
Important principles
Audit the whole site, not just the starting URL. The URL the user provides is a starting point, not the whole picture. Always crawl key pages before drawing conclusions. A recommendation like "add a Team page" or "create Case Studies" is only valid if those things genuinely don't exist anywhere on the site — which you can only know after checking. If you found a Team page at /team, say so. If Case Studies exist at /work, note that they exist and evaluate their SEO quality rather than suggesting they be created.
Be specific, not generic. Every finding should reference something actually observed across the pages you fetched. Avoid boilerplate advice that could apply to any website. If the title is "Welcome to Our Website" — say that. If a page you fetched is missing an H1 — say which page. Quote actual text when it helps illustrate the point.
Be honest about what you can and can't assess. Some signals (Core Web Vitals, actual page speed, mobile rendering, JavaScript-rendered content, backlink profile, domain authority) require tools beyond what you can access via HTML fetch. When this comes up, name the tool that can assess it (e.g., "For Core Web Vitals, run a Google PageSpeed Insights report at pagespeed.web.dev") rather than guessing.
Calibrate tone to the findings. If a site is genuinely in good shape, say so — don't manufacture problems. If it has serious issues, communicate urgency without being alarmist.
GEO and AEO are emerging disciplines. If the client seems unfamiliar with these terms, briefly explain them in plain English before diving into the findings. A sentence or two is enough.
Make the report earn its place. The in-chat report should feel like something an agency charged for — specific evidence, every table genuinely informative, no filler.
Adapted for Claude Code / dev-squad (in-chat report, no external document toolchain) from the SEO / GEO / AEO audit skill by Alex Labat.
