feat(seo-audit): Add comprehensive SEO audit skill
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>
This commit is contained in:
151
ourdigital-custom-skills/12-ourdigital-seo-audit/CLAUDE.md
Normal file
151
ourdigital-custom-skills/12-ourdigital-seo-audit/CLAUDE.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Skill Overview
|
||||
|
||||
**ourdigital-seo-audit** is a comprehensive SEO audit skill that performs technical SEO analysis, schema validation, sitemap/robots.txt checks, and Core Web Vitals measurement. Results are exported to a Notion database.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
12-ourdigital-seo-audit/
|
||||
├── SKILL.md # Skill definition with YAML frontmatter
|
||||
├── scripts/ # Python automation scripts
|
||||
│ ├── base_client.py # Shared utilities: RateLimiter, ConfigManager
|
||||
│ ├── full_audit.py # Main orchestrator (SEOAuditor class)
|
||||
│ ├── gsc_client.py # Google Search Console API
|
||||
│ ├── pagespeed_client.py # PageSpeed Insights API
|
||||
│ ├── schema_validator.py # JSON-LD/Microdata extraction & validation
|
||||
│ ├── schema_generator.py # Generate schema markup from templates
|
||||
│ ├── sitemap_validator.py # XML sitemap validation
|
||||
│ ├── sitemap_crawler.py # Async sitemap URL crawler
|
||||
│ ├── robots_checker.py # Robots.txt parser & rule tester
|
||||
│ ├── page_analyzer.py # On-page SEO analysis
|
||||
│ └── notion_reporter.py # Notion database integration
|
||||
├── templates/
|
||||
│ ├── schema_templates/ # JSON-LD templates (article, faq, product, etc.)
|
||||
│ └── notion_database_schema.json
|
||||
├── reference.md # API documentation
|
||||
└── USER_GUIDE.md # End-user documentation
|
||||
```
|
||||
|
||||
## Script Relationships
|
||||
|
||||
```
|
||||
full_audit.py (orchestrator)
|
||||
├── robots_checker.py → RobotsChecker.analyze()
|
||||
├── sitemap_validator.py → SitemapValidator.validate()
|
||||
├── schema_validator.py → SchemaValidator.validate()
|
||||
├── pagespeed_client.py → PageSpeedClient.analyze()
|
||||
└── notion_reporter.py → NotionReporter.create_audit_report()
|
||||
|
||||
All scripts use:
|
||||
└── base_client.py → ConfigManager (credentials), RateLimiter, BaseAsyncClient
|
||||
```
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Install Dependencies
|
||||
```bash
|
||||
pip install -r scripts/requirements.txt
|
||||
```
|
||||
|
||||
### Run Full SEO Audit
|
||||
```bash
|
||||
python scripts/full_audit.py --url https://example.com --output console
|
||||
python scripts/full_audit.py --url https://example.com --output notion
|
||||
python scripts/full_audit.py --url https://example.com --json
|
||||
```
|
||||
|
||||
### Individual Script Usage
|
||||
```bash
|
||||
# Robots.txt analysis
|
||||
python scripts/robots_checker.py --url https://example.com
|
||||
|
||||
# Sitemap validation
|
||||
python scripts/sitemap_validator.py --url https://example.com/sitemap.xml
|
||||
|
||||
# Schema validation
|
||||
python scripts/schema_validator.py --url https://example.com
|
||||
|
||||
# Schema generation
|
||||
python scripts/schema_generator.py --type organization --url https://example.com
|
||||
|
||||
# Core Web Vitals
|
||||
python scripts/pagespeed_client.py --url https://example.com --strategy mobile
|
||||
|
||||
# Search Console data
|
||||
python scripts/gsc_client.py --site sc-domain:example.com --action summary
|
||||
```
|
||||
|
||||
## Key Classes and Data Flow
|
||||
|
||||
### AuditResult (full_audit.py)
|
||||
Central dataclass holding all audit findings:
|
||||
- `robots`, `sitemap`, `schema`, `performance` - Raw results from each checker
|
||||
- `findings: list[SEOFinding]` - Normalized issues for Notion export
|
||||
- `summary` - Aggregated statistics
|
||||
|
||||
### SEOFinding (notion_reporter.py)
|
||||
Standard format for all audit issues:
|
||||
```python
|
||||
@dataclass
|
||||
class SEOFinding:
|
||||
issue: str # Issue title
|
||||
category: str # Technical SEO, Performance, Schema, etc.
|
||||
priority: str # Critical, High, Medium, Low
|
||||
url: str | None # Affected URL
|
||||
recommendation: str # How to fix
|
||||
audit_id: str # Groups findings from same session
|
||||
```
|
||||
|
||||
### NotionReporter
|
||||
Creates findings in Notion with two modes:
|
||||
1. Individual pages per finding in default database
|
||||
2. Summary page with checklist table via `create_audit_report()`
|
||||
|
||||
Default database: `2c8581e5-8a1e-8035-880b-e38cefc2f3ef`
|
||||
|
||||
## Google API Configuration
|
||||
|
||||
**Service Account**: `~/.credential/ourdigital-seo-agent.json`
|
||||
|
||||
| API | Authentication | Usage |
|
||||
|-----|---------------|-------|
|
||||
| Search Console | Service account | `gsc_client.py` |
|
||||
| PageSpeed Insights | API key (`PAGESPEED_API_KEY`) | `pagespeed_client.py` |
|
||||
| GA4 Analytics | Service account | Traffic data |
|
||||
|
||||
Environment variables are loaded from `~/Workspaces/claude-workspace/.env`.
|
||||
|
||||
## MCP Tool Integration
|
||||
|
||||
The skill uses MCP tools as primary data sources (Tier 1):
|
||||
- `mcp__firecrawl__scrape/crawl` - Web page content extraction
|
||||
- `mcp__perplexity__search` - Competitor research
|
||||
- `mcp__notion__*` - Database operations
|
||||
|
||||
Python scripts are Tier 2 for Google API data collection.
|
||||
|
||||
## Extending the Skill
|
||||
|
||||
### Adding a New Schema Type
|
||||
1. Add JSON template to `templates/schema_templates/`
|
||||
2. Update `REQUIRED_PROPERTIES` and `RECOMMENDED_PROPERTIES` in `schema_validator.py`
|
||||
3. Add type-specific validation in `_validate_type_specific()`
|
||||
|
||||
### Adding a New Audit Check
|
||||
1. Create checker class following pattern in existing scripts
|
||||
2. Return dataclass with `to_dict()` method and `issues` list
|
||||
3. Add processing method in `SEOAuditor` (`_process_*_findings`)
|
||||
4. Wire into `run_audit()` in `full_audit.py`
|
||||
|
||||
## Rate Limits
|
||||
|
||||
| Service | Limit | Handled By |
|
||||
|---------|-------|------------|
|
||||
| Firecrawl | Per plan | MCP |
|
||||
| PageSpeed | 25,000/day | `base_client.py` RateLimiter |
|
||||
| Search Console | 1,200/min | Manual delays |
|
||||
| Notion | 3 req/sec | Semaphore in reporter |
|
||||
Reference in New Issue
Block a user