our-claude-skills/custom-skills/11-seo-on-page-audit/code/CLAUDE.md

CLAUDE.md

Overview

On-page SEO analyzer for single-page optimization: meta tags, headings, links, images, and Open Graph data.

Quick Start

pip install -r scripts/requirements.txt
python scripts/page_analyzer.py --url https://example.com

Scripts

Script	Purpose
page_analyzer.py	Analyze on-page SEO elements
base_client.py	Shared utilities

Usage

# Full page analysis
python scripts/page_analyzer.py --url https://example.com

# JSON output
python scripts/page_analyzer.py --url https://example.com --json

# Analyze multiple pages
python scripts/page_analyzer.py --urls urls.txt

Analysis Categories

Meta Tags

• Title tag (length, keywords)
• Meta description (length, call-to-action)
• Canonical URL
• Robots meta tag

Heading Structure

• H1 presence and count
• Heading hierarchy (H1→H6)
• Keyword placement in headings

Links

• Internal link count
• External link count
• Broken links (4xx/5xx)
• Nofollow distribution

Images

• Alt attribute presence
• Image file sizes
• Lazy loading implementation

Open Graph / Social

• OG title, description, image
• Twitter Card tags
• Social sharing preview

Output

{
  "url": "https://example.com",
  "meta": {
    "title": "Page Title",
    "title_length": 55,
    "description": "...",
    "description_length": 150,
    "canonical": "https://example.com"
  },
  "headings": {
    "h1_count": 1,
    "h1_text": ["Main Heading"],
    "hierarchy_valid": true
  },
  "links": {
    "internal": 25,
    "external": 5,
    "broken": []
  },
  "issues": []
}

Common Issues

Issue	Severity	Recommendation
Missing H1	High	Add single H1 tag
Title too long (>60)	Medium	Shorten to 50-60 chars
No meta description	High	Add compelling description
Images without alt	Medium	Add descriptive alt text
Multiple H1 tags	Medium	Use single H1 only

Dependencies

lxml>=5.1.0
beautifulsoup4>=4.12.0
requests>=2.31.0
python-dotenv>=1.0.0
rich>=13.7.0

Notion Output (Required)

IMPORTANT: All audit reports MUST be saved to the OurDigital SEO Audit Log database.

Database Configuration

Field	Value
Database ID	2c8581e5-8a1e-8035-880b-e38cefc2f3ef
URL	https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef

Required Properties

Property	Type	Description
Issue	Title	Report title (Korean + date)
Site	URL	Audited website URL
Category	Select	Technical SEO, On-page SEO, Performance, Schema/Structured Data, Sitemap, Robots.txt, Content, Local SEO
Priority	Select	Critical, High, Medium, Low
Found Date	Date	Audit date (YYYY-MM-DD)
Audit ID	Rich Text	Format: [TYPE]-YYYYMMDD-NNN

Language Guidelines

• Report content in Korean (한국어)
• Keep technical English terms as-is (e.g., SEO Audit, Core Web Vitals, Schema Markup)
• URLs and code remain unchanged

Example MCP Call

mcp-cli call notion/API-post-page '{"parent": {"database_id": "2c8581e5-8a1e-8035-880b-e38cefc2f3ef"}, "properties": {...}}'