Andrew Yim
9426787ba6
Add ourdigital-seo-audit skill with: - Full site audit orchestrator (full_audit.py) - Google Search Console and PageSpeed API clients - Schema.org JSON-LD validation and generation - XML sitemap and robots.txt validation - Notion database integration for findings export - Core Web Vitals measurement and analysis - 7 schema templates (article, faq, product, etc.) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
495 lines
11 KiB
Markdown
495 lines
11 KiB
Markdown
# OurDigital SEO Audit - User Guide
|
|
|
|
## Table of Contents
|
|
|
|
1. [Overview](#overview)
|
|
2. [Prerequisites](#prerequisites)
|
|
3. [Quick Start](#quick-start)
|
|
4. [Features](#features)
|
|
5. [Usage Examples](#usage-examples)
|
|
6. [API Reference](#api-reference)
|
|
7. [Notion Integration](#notion-integration)
|
|
8. [Troubleshooting](#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
|
|
|
|
```bash
|
|
# 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](https://search.google.com/search-console)
|
|
- GA4: Add service account as Viewer in [Google Analytics](https://analytics.google.com)
|
|
|
|
### 3. API Keys
|
|
|
|
Located in `~/Workspaces/claude-workspace/.env`:
|
|
|
|
```bash
|
|
# 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](https://console.cloud.google.com/apis/library):
|
|
|
|
- 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](https://console.cloud.google.com/apis/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](https://console.cloud.google.com/apis/library)
|
|
- 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"**
|
|
```bash
|
|
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](SKILL.md) for technical details
|
|
3. Check [examples.md](examples.md) for more usage examples
|
|
|
|
---
|
|
|
|
*Last updated: December 2024*
|