our-claude-skills/custom-skills/_archive/seo-audit-agent/USER_GUIDE.md

OurDigital SEO Audit - User Guide

Table of Contents

1. Overview
2. Prerequisites
3. Quick Start
4. Features
5. Usage Examples
6. API Reference
7. Notion Integration
8. Troubleshooting

---

Overview

The ourdigital-seo-audit skill is a comprehensive SEO audit tool for Claude Code that:

• Performs technical SEO analysis
• Validates schema markup (JSON-LD, Microdata, RDFa)
• Checks sitemap and robots.txt configuration
• Measures Core Web Vitals performance
• Integrates with Google APIs (Search Console, Analytics, PageSpeed)
• Exports findings to Notion database

Supported Audit Categories

Category	Description
Technical SEO	HTTPS, canonicals, redirects, crawlability
On-page SEO	Meta tags, headings, images, internal links
Content	Quality, duplication, freshness, E-E-A-T
Local SEO	NAP consistency, citations, LocalBusiness schema
Performance	Core Web Vitals (LCP, CLS, TBT, FCP)
Schema/Structured Data	JSON-LD validation, rich results eligibility
Sitemap	XML validation, URL accessibility
Robots.txt	Directive analysis, blocking issues

---

Prerequisites

1. Python Environment

# Install required packages
cd ~/.claude/skills/ourdigital-seo-audit/scripts
pip install -r requirements.txt

2. Google Cloud Service Account

The skill uses a service account for authenticated APIs:

File: ~/.credential/ourdigital-seo-agent.json
Service Account: ourdigital-seo-agent@ourdigital-insights.iam.gserviceaccount.com
Project: ourdigital-insights

Required permissions:

• Search Console: Add service account email as user in Search Console
• GA4: Add service account as Viewer in Google Analytics

3. API Keys

Located in ~/Workspaces/claude-workspace/.env:

# Google API Key (for PageSpeed, Custom Search, Knowledge Graph)
GOOGLE_API_KEY=your-api-key
PAGESPEED_API_KEY=your-api-key
CUSTOM_SEARCH_API_KEY=your-api-key
CUSTOM_SEARCH_ENGINE_ID=your-cx-id

4. Enabled Google Cloud APIs

Enable these APIs in Google Cloud Console:

• Search Console API
• PageSpeed Insights API
• Google Analytics Admin API
• Google Analytics Data API
• Custom Search API
• Knowledge Graph Search API

---

Quick Start

Run a Full SEO Audit

Perform a comprehensive SEO audit for https://example.com

Check Core Web Vitals

Check Core Web Vitals for https://example.com

Validate Schema Markup

Validate schema markup on https://example.com

Check Sitemap

Validate the sitemap at https://example.com/sitemap.xml

Analyze Robots.txt

Analyze robots.txt for example.com

---

Features

1. Technical SEO Analysis

Checks for:

• HTTPS/SSL implementation
• Canonical URL configuration
• Redirect chains and loops
• 404 error pages
• Mobile-friendliness
• Hreflang tags (international sites)

Command:

Check technical SEO for https://example.com

2. Schema Markup Validation

Extracts and validates structured data:

• JSON-LD (recommended)
• Microdata
• RDFa

Supported schema types:

• Organization / LocalBusiness
• Product / Offer
• Article / BlogPosting
• FAQPage / HowTo
• BreadcrumbList
• WebSite / WebPage

Command:

Validate existing schema markup on https://example.com

3. Schema Generation

Generate JSON-LD markup for your pages:

Command:

Generate Organization schema for https://example.com

Available types:

• organization - Company/organization info
• local_business - Physical business location
• product - E-commerce products
• article - Blog posts and news
• faq - FAQ pages
• breadcrumb - Navigation breadcrumbs
• website - Site-level schema with search

4. Sitemap Validation

Validates XML sitemaps for:

• XML syntax errors
• URL accessibility (HTTP status)
• URL count limits (50,000 max)
• File size limits (50MB max)
• Lastmod date validity
• Index sitemap structure

Command:

Validate the sitemap at https://example.com/sitemap.xml

5. Robots.txt Analysis

Analyzes robots.txt for:

• Syntax validation
• User-agent rules
• Disallow/Allow patterns
• Sitemap declarations
• Critical resource blocking
• URL testing against rules

Command:

Analyze robots.txt for example.com

6. Core Web Vitals

Measures performance metrics:

Metric	Good	Needs Improvement	Poor
LCP (Largest Contentful Paint)	< 2.5s	2.5s - 4.0s	> 4.0s
CLS (Cumulative Layout Shift)	< 0.1	0.1 - 0.25	> 0.25
TBT (Total Blocking Time)	< 200ms	200ms - 600ms	> 600ms
FCP (First Contentful Paint)	< 1.8s	1.8s - 3.0s	> 3.0s

Command:

Check Core Web Vitals for https://example.com

7. Search Console Integration

Access search performance data:

• Top queries and pages
• Click-through rates
• Average positions
• Indexing status

Command:

Get Search Console data for sc-domain:example.com

8. GA4 Analytics Integration

Access traffic and behavior data:

• Page views
• User sessions
• Traffic sources
• Engagement metrics

Available properties:

• OurDigital Lab (218477407)
• OurDigital Journal (413643875)
• OurDigital Blog (489750460)

Command:

Get GA4 traffic data for OurDigital Blog

---

Usage Examples

Example 1: Full Site Audit with Notion Export

Perform a comprehensive SEO audit for https://blog.ourdigital.org and export findings to Notion

This will:

1. Check robots.txt configuration
2. Validate sitemap
3. Analyze schema markup
4. Run PageSpeed analysis
5. Export all findings to the OurDigital SEO Audit Log database

Example 2: Schema Audit Only

Check schema markup on https://blog.ourdigital.org and identify any issues

Example 3: Performance Deep Dive

Analyze Core Web Vitals for https://blog.ourdigital.org and provide optimization recommendations

Example 4: Competitive Analysis

Compare SEO performance between https://blog.ourdigital.org and https://competitor.com

Example 5: Local SEO Audit

Perform local SEO audit for OurDigital in Seoul, Korea

---

API Reference

Python Scripts

All scripts are located in ~/.claude/skills/ourdigital-seo-audit/scripts/

robots_checker.py

python robots_checker.py --url https://example.com

Options:

• --url - Base URL to check
• --test-url - Specific URL to test against rules
• --user-agent - User agent to test (default: Googlebot)

sitemap_validator.py

python sitemap_validator.py --url https://example.com/sitemap.xml

Options:

• --url - Sitemap URL
• --check-urls - Verify URL accessibility (slower)
• --limit - Max URLs to check

schema_validator.py

python schema_validator.py --url https://example.com

Options:

• --url - Page URL to validate
• --check-rich-results - Check Google Rich Results eligibility

schema_generator.py

python schema_generator.py --type organization --url https://example.com

Options:

• --type - Schema type (organization, local_business, product, article, faq, breadcrumb, website)
• --url - Target URL
• --output - Output file (default: stdout)

pagespeed_client.py

python pagespeed_client.py --url https://example.com --strategy mobile

Options:

• --url - URL to analyze
• --strategy - mobile, desktop, or both
• --json - Output as JSON
• --cwv-only - Show only Core Web Vitals

gsc_client.py

python gsc_client.py --site sc-domain:example.com --action summary

Options:

• --site - Site URL (sc-domain: or https://)
• --action - summary, queries, pages, sitemaps, inspect
• --days - Days of data (default: 30)

full_audit.py

python full_audit.py --url https://example.com --output notion

Options:

• --url - URL to audit
• --output - console, notion, or json
• --no-robots - Skip robots.txt check
• --no-sitemap - Skip sitemap validation
• --no-schema - Skip schema validation
• --no-performance - Skip PageSpeed analysis

---

Notion Integration

Default Database

All findings are stored in the OurDigital SEO Audit Log:

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

Database Properties

Property	Type	Description
Issue	Title	Issue title
Site	URL	Audited site URL
Category	Select	Issue category
Priority	Select	Critical / High / Medium / Low
Status	Status	Not started / In progress / Done
URL	URL	Specific page with issue
Found Date	Date	Discovery date
Audit ID	Text	Groups findings by session

Page Content Template

Each finding page contains:

## Description
[Detailed explanation of the issue]

## Impact
⚠️ [Business/ranking impact]

## Recommendation
💡 [Actionable solution]

Filtering Findings

Use Notion filters to view:

• By Site: Filter by Site property
• By Category: Filter by Category (Schema, Performance, etc.)
• By Priority: Filter by Priority (Critical first)
• By Audit: Filter by Audit ID to see all findings from one session

---

Troubleshooting

API Authentication Errors

Error: "Invalid JWT Signature"

• Check that the service account key file exists
• Verify the file path in ~/.credential/ourdigital-seo-agent.json
• Regenerate the key in Google Cloud Console if corrupted

Error: "Requests from referer are blocked"

• Go to API Credentials
• Click on your API key
• Set "Application restrictions" to "None"
• Save and wait 1-2 minutes

Error: "API has not been enabled"

• Enable the required API in Google Cloud Console
• Wait a few minutes for propagation

Search Console Issues

Error: "Site not found"

• Use domain property format: sc-domain:example.com
• Or URL prefix format: https://www.example.com/
• Add service account email as user in Search Console

PageSpeed Rate Limiting

Error: "429 Too Many Requests"

• Wait a few minutes before retrying
• Use an API key for higher quotas
• Batch requests with delays

Notion Integration Issues

Error: "Failed to create page"

• Verify NOTION_API_KEY is set
• Check that the integration has access to the database
• Ensure database properties match expected schema

Python Import Errors

Error: "ModuleNotFoundError"

cd ~/.claude/skills/ourdigital-seo-audit/scripts
pip install -r requirements.txt

---

Support

For issues or feature requests:

1. Check this guide first
2. Review the SKILL.md for technical details
3. Check examples.md for more usage examples

---

Last updated: December 2024