12# SEO Audit Skill
13
14Audit websites for SEO, technical, content, performance, security, JavaScript rendering, and AI readiness using the SEOmator CLI.
15
16SEOmator provides comprehensive website auditing by analyzing website structure and content against **251 rules** across **20 categories**.
17
18It provides a list of issues with severity levels, affected URLs, and actionable fix suggestions.
19
20## Links
21
22* SEOmator npm package: [npmjs.com/package/@seomator/seo-audit](https://www.npmjs.com/package/@seomator/seo-audit)
23* GitHub repository: [github.com/seo-skills/seo-audit-skill](https://github.com/seo-skills/seo-audit-skill)
24* Web UI: [seomator.com/free-seo-audit-tool](https://seomator.com/free-seo-audit-tool)
25
26## What This Skill Does
27
28This skill enables AI agents to audit websites for **251 rules** in **20 categories**, including:
29
30- **Core SEO** (19 rules): Canonical URLs, indexing directives, title uniqueness, canonical conflicts/loops
31- **Performance** (22 rules): LCP, CLS, FCP, TTFB, INP, compression, caching, minification, HTTP/2
32- **Links** (19 rules): Broken links, redirect chains, anchor text, orphan pages, localhost/fragment links
33- **Images** (14 rules): Alt text, dimensions, lazy loading, modern formats, alt length, background images
34- **Security** (16 rules): HTTPS, HSTS, CSP, external link safety, leaked secrets, SSL expiry/protocol
35- **Technical SEO** (13 rules): robots.txt, sitemap.xml, URL structure, 404 pages, soft 404s, error codes
36- **Crawlability** (18 rules): Sitemap conflicts, indexability signals, canonical chains, pagination issues
37- **Structured Data** (13 rules): Schema.org markup, Article, Organization, FAQ, Product, Breadcrumb
38- **JavaScript Rendering** (13 rules): Rendered DOM checks, raw vs rendered mismatches, SSR detection
39- **Accessibility** (12 rules): ARIA labels, color contrast, form labels, landmarks, touch targets
40- **Content** (17 rules): Word count, readability, keyword density, duplicate detection, pixel widths
41- **Social** (9 rules): Open Graph tags, Twitter cards, share buttons, profile links
42- **E-E-A-T** (14 rules): Author bylines, citations, trust signals, about/contact pages, YMYL detection
43- **URL Structure** (14 rules): Keyword slugs, stop words, uppercase, underscores, session IDs, tracking params
44- **Redirects** (8 rules): Redirect loops, types (301/302), meta refresh, JavaScript redirects, broken redirects
45- **Mobile** (5 rules): Font sizes, horizontal scroll, intrusive interstitials, viewport issues
46- **Internationalization** (10 rules): lang attribute, hreflang validation (return links, conflicts, mismatches)
47- **HTML Validation** (9 rules): Doctype, charset, head structure, lorem ipsum, multiple titles/descriptions
48- **AI/GEO Readiness** (5 rules): Semantic HTML, AI bot access, llms.txt, schema drift
49- **Legal Compliance** (1 rule): Cookie consent
50
51The audit crawls the website, analyzes each page against audit rules, and returns a comprehensive report with:
52- Overall health score (0-100) with letter grade (A-F)
53- Category breakdowns with pass/warn/fail counts
54- Specific issues with affected URLs grouped by rule
55- Actionable fix recommendations
56
57## When to Use
58
59Use this skill when you need to:
60- Analyze a website's SEO health
61- Debug technical SEO issues
62- Check for broken links and redirect chains
63- Validate meta tags, canonical URLs, and structured data
64- Audit security headers, SSL, and HTTPS
65- Check accessibility compliance
66- Analyze JavaScript rendering and SSR compatibility
67- Evaluate AI/GEO readiness (semantic HTML, llms.txt, bot access)
68- Detect duplicate content across pages
69- Validate hreflang and internationalization setup
70- Check HTML document structure and validation
71- Generate site audit reports in multiple formats
72- Compare site health before/after changes
73
74## Prerequisites
75
76This skill requires the SEOmator CLI to be installed.
77
78### Installation
79
80```bash
81npm install -g @seomator/seo-audit
82```
83
84### Verify Installation
85
86Check that seomator is installed and the system is ready:
87
88```bash
89seomator self doctor
90```
91
92This checks:
93- Node.js version (18+ recommended)
94- npm availability
95- Chrome/Chromium for Core Web Vitals and JS rendering
96- Write permissions for ~/.seomator
97- Local config file presence
98
99## Setup
100
101Running seomator init creates a seomator.toml config file in the current directory.
102
103```bash
104seomator init # Interactive setup
105seomator init -y # Use defaults
106seomator init --preset blog # Blog-optimized config
107seomator init --preset ecommerce # E-commerce config
108seomator init --preset ci # Minimal CI config
109```
110
111If there is no seomator.toml in the directory, CREATE ONE with seomator init before running audits.
112
113## Usage
114
115### AI Agent Best Practices
116
117**YOU SHOULD always prefer --format llm** - it provides token-optimized XML output specifically designed for AI agents (50-70% smaller than JSON).
118
119When auditing:
1201. **Prefer live websites** over local dev servers for accurate performance and rendering data
1212. **Use --no-cwv for faster audits** when Core Web Vitals and JS rendering checks aren't needed
1223. **Scope fixes as concurrent tasks** when implementing multiple fixes
1234. **Run typechecking/formatting** after implementing fixes (tsc, eslint, prettier, etc.)
124
125### Website Discovery
126
127If the user doesn't provide a website to audit:
1281. Check for local dev server configurations (package.json scripts, .env files)
1292. Look for Vercel/Netlify project links
1303. Check environment variables for deployment URLs
1314. Ask the user which URL to audit
132
133If you have both local and live websites available, **suggest auditing the live site** for accurate results.
134
135### Basic Workflow
136
137```bash
138# Quick single-page audit with LLM output
139seomator audit https://example.com --format llm --no-cwv
140
141# Multi-page crawl (up to 50 pages)
142seomator audit https://example.com --crawl -m 50 --format llm --no-cwv
143
144# Full audit with Core Web Vitals + JS rendering analysis
145seomator audit https://example.com --crawl -m 20 --format llm
146```
147
148### Advanced Options
149
150Force fresh crawl (ignore cache):
151```bash
152seomator audit https://example.com --refresh --format llm
153```
154
155Resume interrupted crawl:
156```bash
157seomator audit https://example.com --resume --format llm
158```
159
160Audit specific categories only:
161```bash
162seomator audit https://example.com -c core,security,js --format llm --no-cwv
163```
164
165Save HTML report for sharing:
166```bash
167seomator audit https://example.com --format html -o report.html
168```
169
170Verbose output for debugging:
171```bash
172seomator audit https://example.com --format llm -v
173```
174
175## Command Reference
176
177### Audit Command Options
178
179| Option | Alias | Description | Default |
180|--------|-------|-------------|---------|
181| --format <fmt> | -f | Output format: console, json, html, markdown, llm | console |
182| --max-pages <n> | -m | Maximum pages to crawl | 10 |
183| --crawl | | Enable multi-page crawl | false |
184| --categories <list> | -c | Comma-separated categories to audit | All |
185| --refresh | -r | Ignore cache, fetch fresh | false |
186| --resume | | Resume interrupted crawl | false |
187| --no-cwv | | Skip Core Web Vitals + JS rendering | false |
188| --verbose | -v | Show progress | false |
189| --output <path> | -o | Output file path | |
190| --config <path> | | Config file path | |
191| --save | | Save to ~/.seomator | false |
192
193### Other Commands
194
195```bash
196seomator init # Create config file
197seomator self doctor # Check system setup
198seomator config --list # Show all config values
199seomator report --list # List past reports
200seomator db stats # Show database statistics
201```
202
203## Output Formats
204
205| Format | Flag | Best For |
206|--------|------|----------|
207| console | --format console | Human terminal output (default) |
208| json | --format json | CI/CD, programmatic processing |
209| html | --format html | Standalone reports, sharing |
210| markdown | --format markdown | Documentation, GitHub |
211| llm | --format llm | **AI agents** (recommended) |
212
213The --format llm output is a compact XML format optimized for token efficiency:
214- **50-70% smaller** than JSON output
215- Issues sorted by severity (critical first)
216- Fix suggestions included for each issue
217- Clean stdout for piping to AI tools
218
219## Examples
220
221### Example 1: Quick Audit with LLM Output
222
223```bash
224# User asks: "Check example.com for SEO issues"
225seomator audit https://example.com --format llm --no-cwv
226```
227
228### Example 2: Deep Crawl for Large Site
229
230```bash
231# User asks: "Do a thorough audit with up to 100 pages"
232seomator audit https://example.com --crawl -m 100 --format llm --no-cwv
233```
234
235### Example 3: Fresh Audit After Changes
236
237```bash
238# User asks: "Re-audit the site, ignore cached results"
239seomator audit https://example.com --refresh --format llm --no-cwv
240```
241
242### Example 4: Generate Shareable Report
243
244```bash
245# User asks: "Create an HTML report I can share"
246seomator audit https://example.com --crawl -m 20 --format html -o seo-report.html
247```
248
249### Example 5: Focus on Specific Areas
250
251```bash
252# User asks: "Just check my JavaScript rendering and redirects"
253seomator audit https://example.com -c js,redirect --format llm
254```
255
256## Evaluating Results
257
258### Score Ranges
259
260| Score | Grade | Meaning |
261|-------|-------|---------|
262| 90-100 | A | Excellent - Minor optimizations only |
263| 80-89 | B | Good - Address warnings |
264| 70-79 | C | Needs Work - Priority fixes required |
265| 50-69 | D | Poor - Multiple critical issues |
266| 0-49 | F | Critical - Major problems to resolve |
267
268### Priority Order (by category weight)
269
270Fix issues in this order for maximum impact:
271
2721. **Core** (12%) - Meta tags, canonical, H1, indexing
2732. **Performance** (12%) - Core Web Vitals + optimization
2743. **Links** (8%) - Internal linking structure
2754. **Images** (8%) - Performance + accessibility
2765. **Security** (8%) - Trust signals, SSL
2776. **Technical SEO** (7%) - Crawling foundation
2787. **Crawlability** (5%) - Indexability, pagination
2798. **Structured Data** (5%) - Rich snippets
2809. **JavaScript Rendering** (5%) - Rendered DOM, SSR
28110. **Content** (5%) - Text quality + duplicates
28211. **Accessibility** (4%) - WCAG compliance
28312. **Social** (3%) - Social sharing
28413. **E-E-A-T** (3%) - Trust, expertise
28514. **URL Structure** (3%) - URL hygiene
28615. **Redirects** (3%) - Redirect chains
28716. **Mobile** (2%) - Viewport, fonts
28817. **Internationalization** (2%) - Hreflang
28918. **HTML Validation** (2%) - Document structure
29019. **AI/GEO Readiness** (2%) - Semantic HTML, AI bots
29120. **Legal Compliance** (1%) - Cookie consent
292
293### Fix by Severity
294
2951. **Failures (status: "fail")** - Must fix immediately
2962. **Warnings (status: "warn")** - Should fix soon
2973. **Passes (status: "pass")** - No action needed
298
299## Output Summary
300
301After implementing fixes, give the user a summary of all changes made.
302
303When planning scope, organize tasks so they can run concurrently as sub-agents to speed up implementation.
304
305## Troubleshooting
306
307### seomator command not found
308
309If you see this error, seomator is not installed or not in your PATH.
310
311**Solution:**
312```bash
313npm install -g @seomator/seo-audit
314```
315
316### Core Web Vitals not measured
317
318If CWV metrics are missing, Chrome/Chromium may not be available.
319
320**Solution:**
3211. Install Chrome, Chromium, or Edge
3222. Run seomator self doctor to verify browser detection
3233. Use --no-cwv to skip CWV if not needed
324
325### Crawl timeout or slow performance
326
327For large sites, audits may take several minutes.
328
329**Solution:**
330- Use --verbose to see progress
331- Limit pages with -m 20 for faster results
332- Use --no-cwv to skip browser-based measurements
333
334### Invalid URL
335
336Ensure the URL includes the protocol:
337
338```bash
339# Wrong
340seomator audit example.com
341
342# Correct
343seomator audit https://example.com
344```
345
346## How It Works
347
3481. **Fetch**: Downloads the page HTML and measures response time
3492. **Parse**: Extracts DOM, meta tags, links, images, structured data
3503. **Enrich**: Fetches robots.txt and sitemap once per audit
3514. **Render** (if CWV enabled): Captures rendered DOM via Playwright for JS rendering analysis
3525. **Crawl** (if enabled): Discovers and fetches linked pages
3536. **Analyze**: Runs 251 audit rules against each page
3547. **Score**: Calculates category and overall weighted scores
3558. **Report**: Generates output in requested format
356
357Results are stored in ~/.seomator/ for later retrieval with seomator report.
358
359## Resources
360
361- **Full rules reference**: See docs/SEO-AUDIT-RULES.md for all 251 rules
362- **Storage architecture**: See docs/STORAGE-ARCHITECTURE.md for database details
363- **CLI help**: seomator --help and seomator <command> --help
364