SEOmator Audit Skill

Source: SEOmator CLI (@seomator/seo-audit v3.0.0), Electron desktop app, project architecture

A comprehensive SEO audit tool with 251 rules across 20 weighted categories. Available as both an npm CLI for scripting and automation, and an Electron desktop app with a visual dashboard, real-time progress tracking, and score history. The self-registering rule pattern makes it straightforward to add new rules without touching core logic — each rule calls defineRule() and gets stored in a global Map via registerRule().

What It Does

• Audits any URL against 251 individual SEO rules
• Categorizes results across 20 weighted categories
• Produces a weighted overall score (pass=100, warn=50, fail=0 per rule)
• Outputs in 5 formats: JSON, HTML, Markdown, XML, CLI table
• Tracks score history over time (Electron app)

20 Categories with Weights

Category	Weight	Focus
Core	12%	Title tags, meta descriptions, headings, canonical
Performance	12%	Page speed, CWV, resource optimization
Links	8%	Internal/external links, broken links, anchor text
Images	8%	Alt text, sizing, format, lazy loading
Security	8%	HTTPS, headers, mixed content
Technical	7%	Robots.txt, sitemap, server config
Crawl	5%	Crawlability, indexation, fetch issues
Schema	5%	Structured data validation
Content	5%	Word count, readability, keyword density
JS Rendering	5%	Client-side rendering, hydration, JS-dependent content
Accessibility	4%	ARIA, contrast, keyboard navigation
Social	3%	Open Graph, Twitter Cards
E-E-A-T	3%	Experience, Expertise, Authority, Trust signals
URL	3%	URL structure, length, special characters
Redirects	3%	Redirect chains, 301/302 usage
Mobile	2%	Responsive design, viewport, touch targets
i18n	2%	Hreflang, language declarations
HTML Validation	2%	W3C compliance, deprecated elements
Geo/AI Readiness	2%	Local SEO, AI Overviews optimization
Legal	1%	Privacy policy, cookie consent

Category weights must sum to exactly 100 — this is validated programmatically.

Scoring Model

• Each rule produces: Pass (100), Warn (50), or Fail (0)
• Category score = weighted average of all rules in that category
• Overall score = weighted average of all category scores (using the weights above)
• Score thresholds: 90+ excellent, 70-89 good, 50-69 needs work, below 50 critical

Self-Registering Rule Pattern

// Each rule file calls defineRule() — no central registry to maintain
defineRule({
  id: 'core-title-length',
  category: 'core',
  severity: 'error',
  check: async (page) => {
    const title = page.title;
    if (!title) return { status: 'fail', message: 'Missing title tag' };
    if (title.length < 30 || title.length > 60) return { status: 'warn', message: `Title length: ${title.length}` };
    return { status: 'pass' };
  }
});
 
// registerRule() stores in global Map — clean, scalable for 251 rules

This pattern means adding a new rule is a single file with a single function call. No imports to update, no registry to maintain.

Dual Delivery

CLI (npm install -g @seomator/seo-audit)

• Run audits from terminal or scripts
• Pipe output to files in any of 5 formats
• Integrate into CI/CD pipelines
• Scriptable for batch URL auditing

Electron Desktop App

• Visual dashboard with category breakdowns
• Real-time progress during audit
• Score history tracking over time
• Dark mode support
• Same audit engine as CLI (shared core)

Technical Constraint

The package.json serves dual purpose:

• main field points to Electron entry
• exports field points to CLI entry

better-sqlite3 (used for score history) requires native rebuild when switching between Electron and CLI contexts. The Electron app needs electron-rebuild for the native module.

5 Output Formats

• JSON — Full structured data, best for programmatic consumption
• HTML — Visual report with charts, good for sharing
• Markdown — Wiki/docs-friendly format
• XML — Integration with enterprise tools
• CLI table — Quick terminal review during development

Integration Opportunities

• GSC engine — Audit scores could feed into the opportunity scoring formula, prioritizing pages with low audit scores AND high search potential
• Blog-Agent-Worker — Run audit on generated content before publishing
• Clawdbot — Audit competitor sites as part of competitive intelligence

Key Takeaways

• 251 rules across 20 categories provides coverage that most single-tool audits miss (especially JS Rendering, E-E-A-T, and AI Readiness)
• The self-registering pattern is the right architecture for rule-heavy systems — eliminates the central registry bottleneck
• Dual CLI + Electron delivery means the same engine serves both automation and manual review workflows
• Category weights must sum to 100 — enforced in code, not just documentation
• Structured outputs work for simple rules; regex JSON parsing is the fallback for dynamic objects (FAQ, schema.org) due to Anthropic API constraints

Related

• gsc-autonomous-seo — Audit scores feed into opportunity scoring
• ecosystem-architecture — Where auditing fits in the content loop
• seo-patterns-learned — Patterns from building the rule system
• blog-agent-worker — Content validation before publishing
• essential-mcp-servers — MCP tools used during development
• marketing-automation-use-cases — Automated audit workflows

Try It

1. Install the CLI: npm install -g @seomator/seo-audit
2. Run a quick audit: seo-audit https://weomedia.com --format json > audit.json
3. Review category breakdowns to identify the weakest areas
4. For ongoing tracking, use the Electron app to build score history over time
5. Consider integrating audit scores into the GSC engine’s opportunity formula for a closed-loop optimization system