/seo-audit
SEO health check for any URL or project landing page. Fetches the page, analyzes meta tags, OG, JSON-LD, sitemap, robots.txt, checks SERP positions for target keywords, and outputs a scored report.
MCP Tools (use if available)
web_search(query, engines, include_raw_content) — SERP position check, competitor analysisproject_info(name) — get project URL if auditing by project name
If MCP tools are not available, use Claude WebSearch/WebFetch as fallback.
Steps
Parse target from $ARGUMENTS.
- If URL (starts with
http): use directly.
- If project name: look up URL from project README, CLAUDE.md, or
docs/prd.md.
- If empty: ask via AskUserQuestion — "Which URL or project to audit?"
Fetch the page via WebFetch. Extract:
<title> tag (length check: 50-60 chars ideal)<meta name="description"> (length check: 150-160 chars ideal)- Open Graph tags:
og:title, og:description, og:image, og:url, og:type
- Twitter Card tags:
twitter:card, twitter:title, twitter:image
- JSON-LD structured data (
<script type="application/ld+json">)
<link rel="canonical"> — canonical URL<html lang="..."> — language tag<link rel="alternate" hreflang="..."> — i18n tags- Heading structure: H1 count (should be exactly 1), H2-H3 hierarchy
Check infrastructure files:
- Fetch
{origin}/sitemap.xml — exists? Valid XML? Page count?
- Fetch
{origin}/robots.txt — exists? Disallow rules? Sitemap reference?
- Fetch
{origin}/favicon.ico — exists?
Forced reasoning — assess before scoring:
Write out before proceeding:
- What's present: [list of found elements]
- What's missing: [list of absent elements]
- Critical issues: [anything that blocks indexing or sharing]
SERP position check — for 3-5 keywords:
- Extract keywords from page title + meta description + H1.
- For each keyword, search via MCP
web_search(query="{keyword}") or WebSearch.
- Record: position of target URL in results (1-10, or "not found").
- Record: top 3 competitors for each keyword.
Score calculation (0-100):
| Check |
Max Points |
Criteria |
| Title tag |
10 |
Exists, 50-60 chars, contains primary keyword |
| Meta description |
10 |
Exists, 150-160 chars, compelling |
| OG tags |
10 |
og:title, og:description, og:image all present |
| JSON-LD |
10 |
Valid structured data present |
| Canonical |
5 |
Present and correct |
| Sitemap |
10 |
Exists, valid, referenced in robots.txt |
| Robots.txt |
5 |
Exists, no overly broad Disallow |
| H1 structure |
5 |
Exactly one H1, descriptive |
| HTTPS |
5 |
Site uses HTTPS |
| Mobile meta |
5 |
Viewport tag present |
| Language |
5 |
lang attribute on <html> |
| Favicon |
5 |
Exists |
| SERP presence |
15 |
Found in top 10 for target keywords |
Write report to docs/seo-audit.md (in project context) or print to console:
# SEO Audit: {URL}
**Date:** {YYYY-MM-DD}
**Score:** {N}/100
## Summary
{2-3 sentence overview of SEO health}
## Checks
| Check | Status | Score | Details |
|-------|--------|-------|---------|
| Title | pass/fail | X/10 | "{actual title}" (N chars) |
| ... | ... | ... | ... |
## SERP Positions
| Keyword | Position | Top Competitors |
|---------|----------|----------------|
| {kw} | #N or N/A | competitor1, competitor2, competitor3 |
## Critical Issues
- {issue with fix recommendation}
## Recommendations (Top 3)
1. {highest impact fix}
2. {second priority}
3. {third priority}
Output summary — print score and top 3 recommendations.
Notes
- Score is relative — 80+ is good for a landing page, 90+ is excellent
- SERP checks are approximations (not real-time ranking data)
- Run periodically after content changes or before launch
Common Issues
Page fetch fails
Cause: URL is behind authentication, CORS, or returns non-HTML.
Fix: Ensure the URL is publicly accessible. For SPAs, check if content is server-rendered.
SERP positions show "not found"
Cause: Site is new or not indexed by search engines.
Fix: This is expected for new sites. Submit sitemap to Google Search Console and re-audit in 2-4 weeks.
Low score despite good content
Cause: Missing infrastructure files (sitemap.xml, robots.txt, JSON-LD).
Fix: These are the highest-impact fixes. Generate sitemap, add robots.txt with sitemap reference, and add JSON-LD structured data.
1---2name: solo-seo-audit3description: SEO health check for any URL — analyzes meta tags, OG, JSON-LD, sitemap, robots.txt, SERP positions, and scores 0-100. Use when user says "check SEO", "audit this page", "SEO score", "check meta tags", or "SERP position". Do NOT use for generating landing content (use /landing-gen) or social media posts (use /content-gen).4license: MIT5---6
7# /seo-audit
8
9SEO health check for any URL or project landing page. Fetches the page, analyzes meta tags, OG, JSON-LD, sitemap, robots.txt, checks SERP positions for target keywords, and outputs a scored report.
10
11## MCP Tools (use if available)
12
13- `web_search(query, engines, include_raw_content)` — SERP position check, competitor analysis
14- `project_info(name)` — get project URL if auditing by project name
15
16If MCP tools are not available, use Claude WebSearch/WebFetch as fallback.
17
18## Steps
19
201. **Parse target** from `$ARGUMENTS`.
21 - If URL (starts with `http`): use directly.
22 - If project name: look up URL from project README, CLAUDE.md, or `docs/prd.md`.
23 - If empty: ask via AskUserQuestion — "Which URL or project to audit?"
24
252. **Fetch the page** via WebFetch. Extract:
26 - `<title>` tag (length check: 50-60 chars ideal)
27 - `<meta name="description">` (length check: 150-160 chars ideal)
28 - Open Graph tags: `og:title`, `og:description`, `og:image`, `og:url`, `og:type`
29 - Twitter Card tags: `twitter:card`, `twitter:title`, `twitter:image`
30 - JSON-LD structured data (`<script type="application/ld+json">`)
31 - `<link rel="canonical">` — canonical URL
32 - `<html lang="...">` — language tag
33 - `<link rel="alternate" hreflang="...">` — i18n tags
34 - Heading structure: H1 count (should be exactly 1), H2-H3 hierarchy
35
363. **Check infrastructure files:**
37 - Fetch `{origin}/sitemap.xml` — exists? Valid XML? Page count?
38 - Fetch `{origin}/robots.txt` — exists? Disallow rules? Sitemap reference?
39 - Fetch `{origin}/favicon.ico` — exists?
40
414. **Forced reasoning — assess before scoring:**
42 Write out before proceeding:
43 - **What's present:** [list of found elements]
44 - **What's missing:** [list of absent elements]
45 - **Critical issues:** [anything that blocks indexing or sharing]
46
475. **SERP position check** — for 3-5 keywords:
48 - Extract keywords from page title + meta description + H1.
49 - For each keyword, search via MCP `web_search(query="{keyword}")` or WebSearch.
50 - Record: position of target URL in results (1-10, or "not found").
51 - Record: top 3 competitors for each keyword.
52
536. **Score calculation** (0-100):
54
55 | Check | Max Points | Criteria |
56 |-------|-----------|----------|
57 | Title tag | 10 | Exists, 50-60 chars, contains primary keyword |
58 | Meta description | 10 | Exists, 150-160 chars, compelling |
59 | OG tags | 10 | og:title, og:description, og:image all present |
60 | JSON-LD | 10 | Valid structured data present |
61 | Canonical | 5 | Present and correct |
62 | Sitemap | 10 | Exists, valid, referenced in robots.txt |
63 | Robots.txt | 5 | Exists, no overly broad Disallow |
64 | H1 structure | 5 | Exactly one H1, descriptive |
65 | HTTPS | 5 | Site uses HTTPS |
66 | Mobile meta | 5 | Viewport tag present |
67 | Language | 5 | `lang` attribute on `<html>` |
68 | Favicon | 5 | Exists |
69 | SERP presence | 15 | Found in top 10 for target keywords |
70
717. **Write report** to `docs/seo-audit.md` (in project context) or print to console:
72
73 ```markdown
74 # SEO Audit: {URL}
75
76 **Date:** {YYYY-MM-DD}
77 **Score:** {N}/100
78
79 ## Summary
80 {2-3 sentence overview of SEO health}
81
82 ## Checks
83
84 | Check | Status | Score | Details |
85 |-------|--------|-------|---------|
86 | Title | pass/fail | X/10 | "{actual title}" (N chars) |
87 | ... | ... | ... | ... |
88
89 ## SERP Positions
90
91 | Keyword | Position | Top Competitors |
92 |---------|----------|----------------|
93 | {kw} | #N or N/A | competitor1, competitor2, competitor3 |
94
95 ## Critical Issues
96 - {issue with fix recommendation}
97
98 ## Recommendations (Top 3)
99 1. {highest impact fix}
100 2. {second priority}
101 3. {third priority}
102 ```
103
1048. **Output summary** — print score and top 3 recommendations.
105
106## Notes
107
108- Score is relative — 80+ is good for a landing page, 90+ is excellent
109- SERP checks are approximations (not real-time ranking data)
110- Run periodically after content changes or before launch
111
112## Common Issues
113
114### Page fetch fails
115**Cause:** URL is behind authentication, CORS, or returns non-HTML.
116**Fix:** Ensure the URL is publicly accessible. For SPAs, check if content is server-rendered.
117
118### SERP positions show "not found"
119**Cause:** Site is new or not indexed by search engines.
120**Fix:** This is expected for new sites. Submit sitemap to Google Search Console and re-audit in 2-4 weeks.
121
122### Low score despite good content
123**Cause:** Missing infrastructure files (sitemap.xml, robots.txt, JSON-LD).
124**Fix:** These are the highest-impact fixes. Generate sitemap, add robots.txt with sitemap reference, and add JSON-LD structured data.
modbender