SEO Analyzer

Static SEO analysis for HTML files using cheerio-based parsing. Validates meta tags, social media tags, heading structure, and structured data. Also includes keyword analysis for content optimization.

Analysis Workflow

Parse HTML with cheerio
Check Critical Issues (P0):
- Title tag presence and length
- Meta description presence and length
- Single H1 tag
- Canonical URL
Check Important Issues (P1):
- Robots meta directives
- Viewport meta
- Heading hierarchy
- Lang attribute
Check Recommended (P2):
- Open Graph tags
- Twitter Cards
- JSON-LD structured data
- Hreflang tags
Generate Report with issues and recommendations

Usage

Installation

cd ${CLAUDE_PLUGIN_ROOT}/skills/seo-analyzer
npm install
npm run build

Run Analysis

# SEO analysis (default)
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/seo-analyzer/src/index.ts path/to/file.html

# SEO analysis with JSON output
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/seo-analyzer/src/index.ts path/to/file.html --json

# Keyword analysis
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/seo-analyzer/src/index.ts path/to/file.html --keywords

# Both SEO and Keyword analysis
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/seo-analyzer/src/index.ts path/to/file.html --both

# Combined with JSON output
npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/seo-analyzer/src/index.ts path/to/file.html --both --json

Using Built Version

# After npm run build
node ${CLAUDE_PLUGIN_ROOT}/skills/seo-analyzer/dist/index.js path/to/file.html

Check Items

P0 - Critical (Indexing/Ranking Impact)

Check	Validation	Impact
Title	Exists, 30-60 chars	Search display
Description	Exists, 70-160 chars	Click-through rate
H1	Exactly one	Content hierarchy
Canonical	Exists, valid URL	Duplicate content

P1 - Important (SEO Quality)

Check	Validation	Impact
Robots	No unintended noindex	Indexing
Viewport	Exists	Mobile SEO
Heading order	h1→h2→h3 sequence	Structure
Lang	Exists on html	i18n SEO

P2 - Recommended (Social/Rich Results)

Check	Validation	Impact
og:title	Exists, ≤95 chars	Social sharing
og:description	Exists	Social sharing
og:image	Exists, valid URL	Social sharing
twitter:card	Exists	Twitter display
JSON-LD	Valid schema	Rich results

Output Format

Text Report

# SEO Analysis Report: index.html

## Summary
- Critical: 1
- Important: 2
- Recommended: 3
- Passed: 8

## Critical Issues (P0)

### 1. Missing Meta Description
**Check**: meta-description
**Fix**: Add <meta name="description" content="Your description here">

## Important Issues (P1)
...

JSON Output

{
  "file": "index.html",
  "timestamp": "2024-01-15T10:00:00Z",
  "confidence": 100,
  "summary": {
    "critical": 1,
    "important": 2,
    "recommended": 3,
    "passed": 8
  },
  "issues": [
    {
      "severity": "critical",
      "check": "meta-description",
      "message": "Missing meta description",
      "fix": "Add <meta name=\"description\" content=\"...\">"
    }
  ],
  "passed": [
    {
      "check": "title",
      "value": "Page Title - Brand",
      "length": 18
    }
  ],
  "warnings": []
}

Detection Features

React/SPA Detection

The analyzer detects client-side rendered applications and adjusts confidence:

Presence of #root or #app container
React/Vue/Angular script references
Empty body with JavaScript bundles

When detected, a warning is added that static analysis may not reflect the rendered page.

Keyword Analysis

The keyword analyzer extracts and scores keywords:

npx tsx src/index.ts file.html --keywords

Outputs:

Primary keywords by score
Key phrases (2-word combinations)
Keyword density
Placement analysis (title, H1, description)
Recommendations for improvement

Keyword Report Example

# Keyword Analysis: index.html

## Stats
- Total words: 1245
- Unique words: 342

## Primary Keywords (by score)

| Keyword | Score | Freq | Title | H1 | Description |
|---------|-------|------|-------|----|-----------:|
| product | 28 | 15 | Y | Y | Y |
| service | 21 | 12 | Y |   | Y |
...

## Recommendations

- Consider adding "product management" to your title tag

Integration with Lookup

For detailed guidance on any issue, reference the seo-lookup skill:

# Look up og:image requirements
cat ${CLAUDE_PLUGIN_ROOT}/skills/seo-lookup/seo-index.json | jq '.["og-tags"]["og:image"]'

# Look up Article schema
cat ${CLAUDE_PLUGIN_ROOT}/skills/seo-lookup/structured-data-index.json | jq '.schemas.Article'

External Validation

After fixing issues, validate with: