---
name: ourdigital-seo-audit
description: Comprehensive SEO audit skill for technical SEO, on-page optimization, content analysis, local SEO, Core Web Vitals assessment, schema markup generation/validation, sitemap validation, and robots.txt analysis. Use when user asks for SEO audit, website analysis, search performance review, schema markup, structured data, sitemap check, robots.txt analysis, or optimization recommendations. Activates for keywords like SEO, audit, search console, rankings, crawlability, indexing, meta tags, Core Web Vitals, local SEO, schema, structured data, sitemap, robots.txt.
allowed-tools: mcp__firecrawl__*, mcp__perplexity__*, mcp__notion__*, mcp__google-drive__*, mcp__memory__*, Read, Write, Edit, Bash(python:*), Bash(pip:*)
---

# OurDigital SEO Audit Skill

## Purpose

Comprehensive SEO audit capability for:
- Technical SEO analysis (crawlability, indexing, site structure)
- On-page SEO optimization (meta tags, headings, content)
- Content quality assessment
- Local SEO evaluation
- Core Web Vitals performance
- Schema markup generation and validation
- XML sitemap validation
- Robots.txt analysis

## Execution Strategy: Three-Tier Approach

Always follow this priority order:

### Tier 1: MCP Tools (Primary)

Use built-in MCP tools first for real-time analysis:

| Tool | Purpose |
|------|---------|
| `mcp__firecrawl__scrape` | Scrape page content and structure |
| `mcp__firecrawl__crawl` | Crawl entire website |
| `mcp__firecrawl__extract` | Extract structured data |
| `mcp__perplexity__search` | Research competitors, best practices |
| `mcp__notion__create-database` | Create findings database |
| `mcp__notion__create-page` | Add audit findings |
| `mcp__google-drive__search` | Access Sheets for output |
| `mcp__memory__create_entities` | Track audit state |

### Tier 2: Python Scripts (Data Collection)

For Google API data and specialized analysis:
- `gsc_client.py` - Search Console performance data
- `pagespeed_client.py` - Core Web Vitals metrics
- `ga4_client.py` - Traffic and user behavior
- `schema_validator.py` - Validate structured data
- `sitemap_validator.py` - Validate XML sitemaps
- `robots_checker.py` - Analyze robots.txt

### Tier 3: Manual Fallback

For data requiring special access:
- Export data for offline analysis
- Manual GBP data entry (API requires enterprise approval)
- Third-party tool integration

## Google API Configuration

### Service Account Credentials

The skill uses `ourdigital-seo-agent` service account for authenticated APIs:

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

### API Status & Configuration

| API | Status | Authentication | Notes |
|-----|--------|----------------|-------|
| Search Console | **WORKING** | Service account | Domain: sc-domain:ourdigital.org |
| PageSpeed Insights | **WORKING** | API key | Higher quotas with key |
| Analytics Data (GA4) | **WORKING** | Service account | Properties: Lab, Journal, Blog |
| Google Trends | **WORKING** | None (pytrends) | No auth required |
| Custom Search JSON | **WORKING** | API key | cx: e5f27994f2bab4bf2 |
| Knowledge Graph | **WORKING** | API key | Entity search |
| Google Sheets | **WORKING** | Service account | Share sheet with service account |

### Environment Variables (Configured)

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

```bash
# Google Service Account (auto-detected)
# ~/.credential/ourdigital-seo-agent.json

# Google API Key (PageSpeed, Custom Search, Knowledge Graph)
GOOGLE_API_KEY=AIzaSyBdfnL3-CVl-ZAKYrLMuaHFR6MASa9ZH1Q
PAGESPEED_API_KEY=AIzaSyBdfnL3-CVl-ZAKYrLMuaHFR6MASa9ZH1Q
CUSTOM_SEARCH_API_KEY=AIzaSyBdfnL3-CVl-ZAKYrLMuaHFR6MASa9ZH1Q
CUSTOM_SEARCH_ENGINE_ID=e5f27994f2bab4bf2
```

### Enabled APIs in Google Cloud Console (ourdigital-insights)

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

## Audit Categories

### 1. Technical SEO
- HTTPS/SSL implementation
- Canonical URL setup
- Redirect chains/loops
- 404 error pages
- Server response times
- Mobile-friendliness
- Crawlability assessment
- Hreflang tags

### 2. On-page SEO
- Title tags (length, uniqueness, keywords)
- Meta descriptions
- Heading hierarchy (H1-H6)
- Image alt attributes
- Internal linking structure
- URL structure
- Open Graph / Twitter Card tags

### 3. Content SEO
- Content quality assessment
- Thin content identification
- Duplicate content detection
- Keyword relevance
- Content freshness
- E-E-A-T signals

### 4. Local SEO
- Google Business Profile optimization
- NAP consistency
- Local citations
- Review management
- LocalBusiness schema markup

### 5. Core Web Vitals
- Largest Contentful Paint (LCP) < 2.5s
- First Input Delay (FID) < 100ms
- Cumulative Layout Shift (CLS) < 0.1
- Interaction to Next Paint (INP) < 200ms
- Time to First Byte (TTFB)
- First Contentful Paint (FCP)

### 6. Schema/Structured Data
- Extract existing schema (JSON-LD, Microdata, RDFa)
- Validate against schema.org vocabulary
- Check Google Rich Results compatibility
- Generate missing schema markup
- Support: Organization, LocalBusiness, Product, Article, FAQ, Breadcrumb, WebSite

### 7. Sitemap Validation
- XML syntax validation
- URL accessibility (HTTP status)
- URL count limits (50,000 max)
- File size limits (50MB max)
- Lastmod dates validity
- Index sitemap structure

### 8. Robots.txt Analysis
- Syntax validation
- User-agent rules review
- Disallow/Allow patterns
- Sitemap declarations
- Critical resources access
- URL testing against rules

## Report Output

### Default Notion Database

All SEO audit findings are stored in the centralized **OurDigital SEO Audit Log**:

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

### Notion Database Schema

**Database Properties (Metadata)**

| Property | Type | Values | Description |
|----------|------|--------|-------------|
| Issue | Title | Issue description | Primary identifier |
| Site | URL | Website URL | Audited site (e.g., https://blog.ourdigital.org) |
| Category | Select | Technical SEO, On-page SEO, Content, Local SEO, Performance, Schema/Structured Data, Sitemap, Robots.txt | Issue classification |
| Priority | Select | Critical, High, Medium, Low | Fix priority |
| Status | Status | Not started, In progress, Done | Tracking status |
| URL | URL | Affected URL | Specific page with issue |
| Found Date | Date | Discovery date | When issue was found |
| Audit ID | Rich Text | Audit identifier | Groups findings from same audit session |

**Page Content Template**

Each finding page contains structured content blocks:

```
## Description
[Detailed explanation of the issue]

## Impact
⚠️ [Business/ranking impact callout]

## Recommendation
💡 [Actionable solution callout]
```

### Report Categories

1. **Required Actions** (Critical/High Priority)
   - Security issues, indexing blocks, major errors

2. **Quick Wins** (Easy fixes with high impact)
   - Missing meta tags, schema markup, image optimization

3. **Further Investigation**
   - Complex issues needing deeper analysis

4. **Items to Monitor**
   - Performance metrics, ranking changes, crawl stats

## Operational Guidelines

### Before Any Audit

1. **Gather context**: Ask for target URL, business type, priorities
2. **Check access**: Verify MCP tools are available
3. **Set scope**: Full site vs specific pages

### During Audit

1. Use Firecrawl for initial site analysis
2. Run Python scripts for Google API data
3. Validate schema, sitemap, robots.txt
4. Document findings in Notion

### Rate Limits

| Service | Limit | Strategy |
|---------|-------|----------|
| Firecrawl | Per plan | Use crawl for site-wide |
| PageSpeed | 25,000/day | Batch critical pages |
| Search Console | 1,200/min | Use async with delays |
| Notion | 3 req/sec | Implement semaphore |

## Quick Commands

### Full Site Audit
```
Perform a comprehensive SEO audit for [URL]
```

### Technical SEO Check
```
Check technical SEO for [URL] including crawlability and indexing
```

### Schema Generation
```
Generate [type] schema markup for [URL/content]
```

### Schema Validation
```
Validate existing schema markup on [URL]
```

### Sitemap Check
```
Validate the sitemap at [sitemap URL]
```

### Robots.txt Analysis
```
Analyze robots.txt for [domain]
```

### Core Web Vitals
```
Check Core Web Vitals for [URL]
```

### Local SEO Assessment
```
Perform local SEO audit for [business name] in [location]
```

## Script Usage

### Schema Generator
```bash
python scripts/schema_generator.py --type organization --url https://example.com
```

### Schema Validator
```bash
python scripts/schema_validator.py --url https://example.com
```

### Sitemap Validator
```bash
python scripts/sitemap_validator.py --url https://example.com/sitemap.xml
```

### Robots.txt Checker
```bash
python scripts/robots_checker.py --url https://example.com/robots.txt
```

### Full Audit
```bash
python scripts/full_audit.py --url https://example.com --output notion
```

## Limitations

- Google Business Profile API requires enterprise approval
- Some competitive analysis limited to public data
- Large sites (10,000+ pages) require extended crawl time
- Real-time ranking data requires third-party tools

## Related Resources

- `reference.md` - Detailed API documentation
- `examples.md` - Usage examples
- `templates/` - Schema and report templates
- `scripts/` - Python automation scripts
