| name | seo-audit |
| description | When the user wants to audit or diagnose SEO issues — "technical SEO," "why am I not ranking," "meta tags review," "my traffic dropped," "Google update hit me," "core web vitals," "crawl errors," "indexing issues," or even a vague "my SEO is bad." For pages at scale, see programmatic-seo. For structured data, see schema-markup. For AI search, see ai-seo. |
| category | marketing |
| tier | on-demand |
SEO Audit
Identify SEO issues and provide actionable recommendations to improve organic search performance.
Initial Assessment
Product context: If .agents/product-marketing-context.md exists (or .claude/product-marketing-context.md in older setups), read it first and tailor output to it; only ask for what it doesn't cover.
Before auditing, understand:
- Site Context — site type (SaaS, e-commerce, blog, etc.); primary business goal for SEO; priority keywords/topics
- Current State — known issues or concerns; current organic traffic level; recent changes or migrations
- Scope — full site or specific pages; technical + on-page or one focus area; access to Search Console / analytics
Audit Framework
Schema Markup Detection Limitation
web_fetch and curl cannot reliably detect structured data / schema markup. Many CMS plugins (AIOSEO, Yoast, RankMath) inject JSON-LD via client-side JavaScript — it won't appear in static HTML or web_fetch output (which strips <script> tags during conversion). Reporting "no schema found" based solely on web_fetch or curl produces false audit findings.
To accurately check schema markup, use one of:
- Browser tool — render the page and run:
document.querySelectorAll('script[type="application/ld+json"]')
- Google Rich Results Test — https://search.google.com/test/rich-results
- Screaming Frog export — if the client provides one, use it (SF renders JavaScript)
Priority Order
- Crawlability & Indexation (can Google find and index it?)
- Technical Foundations (is the site fast and functional?)
- On-Page Optimization (is content optimized?)
- Content Quality (does it deserve to rank?)
- Authority & Links (does it have credibility?)
Technical SEO Audit
Crawlability
Robots.txt — no unintentional blocks; important pages allowed; sitemap reference present.
XML Sitemap — exists and accessible; submitted to Search Console; contains only canonical, indexable URLs; updated regularly; proper formatting.
Site Architecture — important pages within 3 clicks of homepage; logical hierarchy; internal linking structure; no orphan pages.
Crawl Budget Issues (large sites) — parameterized URLs under control; faceted navigation handled properly; infinite scroll with pagination fallback; no session IDs in URLs.
Indexation
Index Status — site:domain.com check; Search Console coverage report; compare indexed vs. expected.
Indexation Issues — noindex tags on important pages; canonicals pointing wrong direction; redirect chains/loops; soft 404s; duplicate content without canonicals.
Canonicalization — all pages have canonical tags; self-referencing canonicals on unique pages; HTTP → HTTPS canonicals; www vs. non-www consistency; trailing slash consistency.
Site Speed & Core Web Vitals
Core Web Vitals — LCP (Largest Contentful Paint) < 2.5s; INP (Interaction to Next Paint) < 200ms; CLS (Cumulative Layout Shift) < 0.1.
Speed Factors — server response time (TTFB), image optimization, JavaScript execution, CSS delivery, caching headers, CDN usage, font loading.
Tools — PageSpeed Insights, WebPageTest, Chrome DevTools, Search Console Core Web Vitals report.
Mobile-Friendliness
Responsive design (not separate m. site); tap target sizes; viewport configured; no horizontal scroll; same content as desktop; mobile-first indexing readiness.
Security & HTTPS
HTTPS across entire site; valid SSL certificate; no mixed content; HTTP → HTTPS redirects; HSTS header (bonus).
URL Structure
Readable, descriptive URLs; keywords where natural; consistent structure; no unnecessary parameters; lowercase and hyphen-separated.
On-Page SEO Audit
Title Tags
Check for: unique titles per page; primary keyword near beginning; 50-60 characters (visible in SERP); compelling and click-worthy; brand name placement (end, usually).
Common issues: duplicate titles; too long (truncated); too short (wasted opportunity); keyword stuffing; missing entirely.
Meta Descriptions
Check for: unique descriptions per page; 150-160 characters; includes primary keyword; clear value proposition; call to action.
Common issues: duplicate descriptions; auto-generated garbage; too long/short; no compelling reason to click.
Heading Structure
Check for: one H1 per page; H1 contains primary keyword; logical hierarchy (H1 → H2 → H3); headings describe content, not just styling.
Common issues: multiple H1s; skipped levels (H1 → H3); headings used for styling only; no H1.
Content Optimization
Primary Page Content — keyword in first 100 words; related keywords naturally used; sufficient depth/length for topic; answers search intent; better than competitors.
Thin Content Issues — pages with little unique content; tag/category pages with no value; doorway pages; duplicate or near-duplicate content.
Image Optimization
Descriptive file names; alt text on all images that describes the image; compressed file sizes; modern formats (WebP); lazy loading; responsive images.
Internal Linking
Check for: important pages well-linked; descriptive anchor text; logical link relationships; no broken internal links; reasonable link count per page.
Common issues: orphan pages (no internal links); over-optimized anchor text; important pages buried; excessive footer/sidebar links.
Keyword Targeting
Per Page — clear primary keyword target; title, H1, URL aligned; content satisfies search intent; not competing with other pages (cannibalization).
Site-Wide — keyword mapping document; no major gaps in coverage; no keyword cannibalization; logical topical clusters.
Content Quality Assessment
E-E-A-T Signals
Experience — first-hand experience demonstrated; original insights/data; real examples and case studies.
Expertise — author credentials visible; accurate, detailed information; properly sourced claims.
Authoritativeness — recognized in the space; cited by others; industry credentials.
Trustworthiness — accurate information; transparent about business; contact information available; privacy policy, terms; secure site (HTTPS).
Content Depth
Comprehensive coverage; answers follow-up questions; better than top-ranking competitors; updated and current.
User Engagement Signals
Time on page; bounce rate in context; pages per session; return visits.
Common Issues by Site Type
SaaS/Product Sites
Product pages lack content depth; blog not integrated with product pages; missing comparison/alternative pages; thin feature pages; no glossary/educational content.
E-commerce
Thin category pages; duplicate product descriptions; missing product schema; faceted navigation creating duplicates; mishandled out-of-stock pages.
Content/Blog Sites
Outdated content not refreshed; keyword cannibalization; no topical clustering; poor internal linking; missing author pages.
Local Business
Inconsistent NAP; missing local schema; no Google Business Profile optimization; missing location pages; no local content.
Output Format
Audit Report Structure
Executive Summary — overall health assessment; top 3-5 priority issues; quick wins identified.
Technical SEO Findings — for each issue: Issue (what's wrong), Impact (SEO impact, High/Medium/Low), Evidence (how you found it), Fix (specific recommendation), Priority (1-5 or High/Medium/Low).
On-Page SEO Findings and Content Findings — same format.
Prioritized Action Plan
- Critical fixes (blocking indexation/ranking)
- High-impact improvements
- Quick wins (easy, immediate benefit)
- Long-term recommendations
References
- AI Writing Detection: Common AI writing patterns to avoid (em dashes, overused phrases, filler words)
- For AI search optimization (AEO, GEO, LLMO, AI Overviews), see the ai-seo skill
Tools Referenced
Free — Google Search Console (essential); Google PageSpeed Insights; Bing Webmaster Tools; Rich Results Test (use this for schema validation — it renders JavaScript); Mobile-Friendly Test; Schema Validator.
Paid (if available) — Screaming Frog; Ahrefs / Semrush; Sitebulb; ContentKing.
Schema detection: web_fetch/curl can't see JS-injected schema — use the browser tool, Rich Results Test, or Screaming Frog (they render JavaScript). See Schema Markup Detection Limitation above.
Task-Specific Questions
- What pages/keywords matter most?
- Do you have Search Console access?
- Any recent changes or migrations?
- Who are your top organic competitors?
- What's your current organic traffic baseline?
Related Skills
- ai-seo: For optimizing content for AI search engines (AEO, GEO, LLMO)
- programmatic-seo: For building SEO pages at scale
- site-architecture: For page hierarchy, navigation design, and URL structure
- schema-markup: For implementing structured data
- page-cro: For optimizing pages for conversion (not just ranking)
- analytics-tracking: For measuring SEO performance
