directory changes and restructuring
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
494
custom-skills/_archive/seo-audit-agent/USER_GUIDE.md
Normal file
494
custom-skills/_archive/seo-audit-agent/USER_GUIDE.md
Normal file
@@ -0,0 +1,494 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user