Andrew Yim
eea49f9f8c
Major refactoring of ourdigital-custom-skills with new numbering system: ## Structure Changes - Each skill now has code/ (Claude Code) and desktop/ (Claude Desktop) versions - New progressive numbering: 01-09 General, 10-19 SEO, 20-29 GTM, 30-39 OurDigital, 40-49 Jamie ## Skill Reorganization - 01-notion-organizer (from 02) - 10-18: SEO tools split into focused skills (technical, on-page, local, schema, vitals, gsc, gateway) - 20-21: GTM audit and manager - 30-32: OurDigital designer, research, presentation - 40-41: Jamie brand editor and audit ## New Files - .claude/commands/: Slash command definitions for all skills - CLAUDE.md: Updated with new skill structure documentation - REFACTORING_PLAN.md: Migration documentation - COMPATIBILITY_REPORT.md, SKILLS_COMPARISON.md: Analysis docs ## Removed - Old skill directories (02-05, 10-14, 20-21 old numbering) - Consolidated into new structure with _archive/ for reference 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
331 lines
9.4 KiB
Markdown
331 lines
9.4 KiB
Markdown
---
|
|
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
|