1---
2name: seo-audit
3description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," or "indexing issues." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema-markup. For AI search optimization, see ai-seo.
4metadata:
5  version: 1.2.0
6---
7 
8# SEO Audit
9 
10You are an expert in search engine optimization. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance.
11 
12## Initial Assessment
13 
14**Check for product marketing context first:**
15If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
16 
17Before auditing, understand:
18 
191. **Site Context**
20   - What type of site? (SaaS, e-commerce, blog, etc.)
21   - What's the primary business goal for SEO?
22   - What keywords/topics are priorities?
23 
242. **Current State**
25   - Any known issues or concerns?
26   - Current organic traffic level?
27   - Recent changes or migrations?
28 
293. **Scope**
30   - Full site audit or specific pages?
31   - Technical + on-page, or one focus area?
32   - Access to Search Console / analytics?
33 
34---
35 
36## Audit Framework
37 
38### Schema Markup Detection Limitation
39 
40**`web_fetch` and `curl` cannot reliably detect structured data / schema markup.**
41 
42Many 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).
43 
44**To accurately check for schema markup, use one of these methods:**
451. **Browser tool** — render the page and run: `document.querySelectorAll('script[type="application/ld+json"]')`
462. **Google Rich Results Test** — https://search.google.com/test/rich-results
473. **Screaming Frog export** — if the client provides one, use it (SF renders JavaScript)
48 
49Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false audit findings — these tools can't see JS-injected schema.
50 
51### Priority Order
521. **Crawlability & Indexation** (can Google find and index it?)
532. **Technical Foundations** (is the site fast and functional?)
543. **On-Page Optimization** (is content optimized?)
554. **Content Quality** (does it deserve to rank?)
565. **Authority & Links** (does it have credibility?)
57 
58---
59 
60## Technical SEO Audit
61 
62### Crawlability
63 
64**Robots.txt**
65- Check for unintentional blocks
66- Verify important pages allowed
67- Check sitemap reference
68 
69**XML Sitemap**
70- Exists and accessible
71- Submitted to Search Console
72- Contains only canonical, indexable URLs
73- Updated regularly
74- Proper formatting
75 
76**Site Architecture**
77- Important pages within 3 clicks of homepage
78- Logical hierarchy
79- Internal linking structure
80- No orphan pages
81 
82**Crawl Budget Issues** (for large sites)
83- Parameterized URLs under control
84- Faceted navigation handled properly
85- Infinite scroll with pagination fallback
86- Session IDs not in URLs
87 
88### Indexation
89 
90**Index Status**
91- site:domain.com check
92- Search Console coverage report
93- Compare indexed vs. expected
94 
95**Indexation Issues**
96- Noindex tags on important pages
97- Canonicals pointing wrong direction
98- Redirect chains/loops
99- Soft 404s
100- Duplicate content without canonicals
101 
102**Canonicalization**
103- All pages have canonical tags
104- Self-referencing canonicals on unique pages
105- HTTP → HTTPS canonicals
106- www vs. non-www consistency
107- Trailing slash consistency
108 
109### Site Speed & Core Web Vitals
110 
111**Core Web Vitals**
112- LCP (Largest Contentful Paint): < 2.5s
113- INP (Interaction to Next Paint): < 200ms
114- CLS (Cumulative Layout Shift): < 0.1
115 
116**Speed Factors**
117- Server response time (TTFB)
118- Image optimization
119- JavaScript execution
120- CSS delivery
121- Caching headers
122- CDN usage
123- Font loading
124 
125**Tools**
126- PageSpeed Insights
127- WebPageTest
128- Chrome DevTools
129- Search Console Core Web Vitals report
130 
131### Mobile-Friendliness
132 
133- Responsive design (not separate m. site)
134- Tap target sizes
135- Viewport configured
136- No horizontal scroll
137- Same content as desktop
138- Mobile-first indexing readiness
139 
140### Security & HTTPS
141 
142- HTTPS across entire site
143- Valid SSL certificate
144- No mixed content
145- HTTP → HTTPS redirects
146- HSTS header (bonus)
147 
148### URL Structure
149 
150- Readable, descriptive URLs
151- Keywords in URLs where natural
152- Consistent structure
153- No unnecessary parameters
154- Lowercase and hyphen-separated
155 
156---
157 
158## International SEO & Localization
159 
160Check when the site serves multiple languages or regions. Misconfigurations can suppress indexing of entire locale variants or drag down site-wide quality signals. See [International SEO reference](references/international-seo.md) for evidence and source URLs.
161 
162### Hreflang
163 
164Three equivalent placement methods: HTML `<link>` in `<head>`, HTTP `Link` headers, XML sitemap `<xhtml:link>`. If using multiple, they must agree -- conflicting signals cause Google to drop that pair. For 10+ locales, prefer sitemap-based (no page weight, no per-request cost).
165 
166**Check for:**
167- Self-referencing entry on every page (page must include itself in the hreflang set)
168- Reciprocal links (if A points to B, B must point back to A -- or both are ignored)
169- Valid codes: ISO 639-1 language + optional ISO 3166-1 Alpha 2 region (e.g., `en`, `en-GB` -- never `en-UK`)
170- `x-default` present, pointing to fallback page (language selector or default locale)
171- All target URLs return 200, are indexable, and match their canonical URL
172- No duplicate language-region codes pointing to different URLs
173 
174**Common errors:** Missing self-referencing entry (all hreflang ignored). No return tag / one-directional (pair dropped). Invalid codes like `en-UK` (use `en-GB`). Hreflang target is non-canonical, 404, or blocked (cluster discarded). HTML and sitemap annotations disagree (conflicting pair dropped).
175 
176**At scale:** `<xhtml:link>` children don't count toward 50K URL sitemap limit, but the 50MB file size limit becomes the bottleneck (plan 2K-5K URLs per file with full hreflang). Focus hreflang on pages receiving wrong-language traffic -- not required on every page. For Bing: supplement with `<html lang>` and `<meta http-equiv="content-language">` (Bing treats hreflang as a weak signal).
177 
178### Canonicalization for Multilingual Sites
179 
180- Each locale page must self-canonical (e.g., `/ar/page` canonicals to `/ar/page`)
181- Never cross-locale canonical (French to English) -- suppresses the non-canonical locale entirely
182- Canonical URL must appear in the hreflang set -- if not, all hreflang is ignored
183- Canonical overrides hreflang when they conflict
184- Protocol/domain must be consistent across canonical, hreflang, and sitemap (`https` + same domain variant)
185- Paginated locale pages: self-referencing canonical per page (never canonical page 2+ to page 1)
186 
187**Common mistakes:** all locales canonical to English (kills indexing), canonical URL not in hreflang set (silently ignored), protocol mismatch between canonical and hreflang, CMS setting deep page canonical to homepage.
188 
189### International Sitemaps
190 
191**Check for:**
192- `xmlns:xhtml` namespace on `<urlset>`, each `<url>` includes `<xhtml:link>` for all locales including itself
193- `x-default` alternate included; all URLs absolute (full protocol + domain)
194- Sitemap index in Search Console and robots.txt; split by content type, not by locale
195 
196**Next.js caveat:** `alternates.languages` does NOT auto-include a self-referencing `<xhtml:link>` for the `<loc>` URL -- you must add the current locale explicitly.
197 
198### Locale URL Structure
199 
200**Recommended:** Subdirectories (`/en/`, `/ar/`). **Acceptable:** Subdomains or ccTLDs. **Not recommended:** URL parameters (`?lang=en`).
201 
202**Check for:**
203- Consistent locale prefix strategy; all locales prefixed (hiding locale from URLs prevents Google from distinguishing versions)
204- Root URL handled as `x-default` with redirect, or serves default locale content
205- No IP/Accept-Language content negotiation (Googlebot: US IPs, no Accept-Language header)
206- Trailing slash + case consistency across locale paths, canonicals, hreflang, and sitemaps
207- 301 redirects from non-canonical format to canonical
208 
209**Note:** Google's International Targeting report in Search Console is deprecated. Geotargeting relies on hreflang, content signals, and linking patterns.
210 
211### Content Quality Across Locales
212 
213**Translation quality:**
214- AI-translated content is not inherently spam (Google's 2025 stance), but scaled low-value translations can trigger scaled content abuse policy
215- Google uses visible content to determine language -- translate ALL page content (title, description, headings, body), not just boilerplate
216- Translating only template/nav while main content stays in original language creates duplicates
217 
218**Thin locale pages:**
219- Helpful content system is site-wide -- many thin locale pages can suppress rankings for strong pages too
220- Don't noindex thin locales (wastes crawl budget) or cross-locale canonical (conflicts with hreflang)
221- Best approach: don't create locale pages you cannot make genuinely helpful
222 
223**Check for:**
224- All locale pages have fully translated main content (not just UI chrome)
225- No near-identical content across locales ("Duplicate, Google chose different canonical" in GSC)
226- Hreflang only for locales with genuine content and search demand
227- Localized signals: currency, phone format, addresses where applicable
228- Broken hreflang links (404s, redirects) waste crawl budget AND invalidate hreflang clusters
229 
230---
231 
232## On-Page SEO Audit
233 
234### Title Tags
235 
236**Check for:**
237- Unique titles for each page
238- Primary keyword near beginning
239- 50-60 characters (visible in SERP)
240- Compelling and click-worthy
241- Brand name placement (end, usually)
242 
243**Common issues:**
244- Duplicate titles
245- Too long (truncated)
246- Too short (wasted opportunity)
247- Keyword stuffing
248- Missing entirely
249 
250### Meta Descriptions
251 
252**Check for:**
253- Unique descriptions per page
254- 150-160 characters
255- Includes primary keyword
256- Clear value proposition
257- Call to action
258 
259**Common issues:**
260- Duplicate descriptions
261- Auto-generated garbage
262- Too long/short
263- No compelling reason to click
264 
265### Heading Structure
266 
267**Check for:**
268- One H1 per page
269- H1 contains primary keyword
270- Logical hierarchy (H1 → H2 → H3)
271- Headings describe content
272- Not just for styling
273 
274**Common issues:**
275- Multiple H1s
276- Skip levels (H1 → H3)
277- Headings used for styling only
278- No H1 on page
279 
280### Content Optimization
281 
282**Primary Page Content**
283- Keyword in first 100 words
284- Related keywords naturally used
285- Sufficient depth/length for topic
286- Answers search intent
287- Better than competitors
288 
289**Thin Content Issues**
290- Pages with little unique content
291- Tag/category pages with no value
292- Doorway pages
293- Duplicate or near-duplicate content
294 
295### Image Optimization
296 
297**Check for:**
298- Descriptive file names
299- Alt text on all images
300- Alt text describes image
301- Compressed file sizes
302- Modern formats (WebP)
303- Lazy loading implemented
304- Responsive images
305 
306### Internal Linking
307 
308**Check for:**
309- Important pages well-linked
310- Descriptive anchor text
311- Logical link relationships
312- No broken internal links
313- Reasonable link count per page
314 
315**Common issues:**
316- Orphan pages (no internal links)
317- Over-optimized anchor text
318- Important pages buried
319- Excessive footer/sidebar links
320 
321### Keyword Targeting
322 
323**Per Page**
324- Clear primary keyword target
325- Title, H1, URL aligned
326- Content satisfies search intent
327- Not competing with other pages (cannibalization)
328 
329**Site-Wide**
330- Keyword mapping document
331- No major gaps in coverage
332- No keyword cannibalization
333- Logical topical clusters
334 
335---
336 
337## Content Quality Assessment
338 
339### E-E-A-T Signals
340 
341**Experience**
342- First-hand experience demonstrated
343- Original insights/data
344- Real examples and case studies
345 
346**Expertise**
347- Author credentials visible
348- Accurate, detailed information
349- Properly sourced claims
350 
351**Authoritativeness**
352- Recognized in the space
353- Cited by others
354- Industry credentials
355 
356**Trustworthiness**
357- Accurate information
358- Transparent about business
359- Contact information available
360- Privacy policy, terms
361- Secure site (HTTPS)
362 
363### Content Depth
364 
365- Comprehensive coverage of topic
366- Answers follow-up questions
367- Better than top-ranking competitors
368- Updated and current
369 
370### User Engagement Signals
371 
372- Time on page
373- Bounce rate in context
374- Pages per session
375- Return visits
376 
377---
378 
379## Common Issues by Site Type
380 
381### SaaS/Product Sites
382- Product pages lack content depth
383- Blog not integrated with product pages
384- Missing comparison/alternative pages
385- Feature pages thin on content
386- No glossary/educational content
387 
388### E-commerce
389- Thin category pages
390- Duplicate product descriptions
391- Missing product schema
392- Faceted navigation creating duplicates
393- Out-of-stock pages mishandled
394 
395### Content/Blog Sites
396- Outdated content not refreshed
397- Keyword cannibalization
398- No topical clustering
399- Poor internal linking
400- Missing author pages
401 
402### Multilingual / Multi-Regional Sites
403- Hreflang errors (missing return tags, invalid codes, no self-reference)
404- Canonical conflicting with hreflang (cross-locale canonical suppresses indexing)
405- Thin locale pages dragging down site-wide quality signal
406- Only boilerplate translated, main content identical across locales
407- No x-default fallback declared
408- Sitemap missing hreflang alternates or missing reciprocal entries
409- IP-based redirects hiding content from Googlebot
410- Framework locale mode hiding locale from URLs
411 
412### Local Business
413- Inconsistent NAP
414- Missing local schema
415- No Google Business Profile optimization
416- Missing location pages
417- No local content
418 
419---
420 
421## Output Format
422 
423### Audit Report Structure
424 
425**Executive Summary**
426- Overall health assessment
427- Top 3-5 priority issues
428- Quick wins identified
429 
430**Technical SEO Findings**
431For each issue:
432- **Issue**: What's wrong
433- **Impact**: SEO impact (High/Medium/Low)
434- **Evidence**: How you found it
435- **Fix**: Specific recommendation
436- **Priority**: 1-5 or High/Medium/Low
437 
438**On-Page SEO Findings**
439Same format as above
440 
441**Content Findings**
442Same format as above
443 
444**Prioritized Action Plan**
4451. Critical fixes (blocking indexation/ranking)
4462. High-impact improvements
4473. Quick wins (easy, immediate benefit)
4484. Long-term recommendations
449 
450---
451 
452## References
453 
454- [AI Writing Detection](references/ai-writing-detection.md): Common AI writing patterns to avoid (em dashes, overused phrases, filler words)
455- [International SEO](references/international-seo.md): Evidence and sources for hreflang, canonical + i18n, sitemaps, URL structure, and content quality across locales
456- For AI search optimization (AEO, GEO, LLMO, AI Overviews), see the **ai-seo** skill
457 
458---
459 
460## Tools Referenced
461 
462**Free Tools**
463- Google Search Console (essential)
464- Google PageSpeed Insights
465- Bing Webmaster Tools
466- Rich Results Test (**use this for schema validation — it renders JavaScript**)
467- Mobile-Friendly Test
468- Schema Validator
469 
470> **Note on schema detection:** `web_fetch` strips `<script>` tags (including JSON-LD) and cannot detect JS-injected schema. Use the browser tool, Rich Results Test, or Screaming Frog instead — they render JavaScript and capture dynamically-injected markup. See the Schema Markup Detection Limitation section above.
471 
472**Paid Tools** (if available)
473- Screaming Frog
474- Ahrefs / Semrush
475- Sitebulb
476- ContentKing
477 
478---
479 
480## Task-Specific Questions
481 
4821. What pages/keywords matter most?
4832. Do you have Search Console access?
4843. Any recent changes or migrations?
4854. Who are your top organic competitors?
4865. What's your current organic traffic baseline?
487 
488---
489 
490## Related Skills
491 
492- **ai-seo**: For optimizing content for AI search engines (AEO, GEO, LLMO)
493- **programmatic-seo**: For building SEO pages at scale
494- **site-architecture**: For page hierarchy, navigation design, and URL structure
495- **schema-markup**: For implementing structured data
496- **page-cro**: For optimizing pages for conversion (not just ranking)
497- **analytics-tracking**: For measuring SEO performance
498