ourdigital/our-claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
173d526cf3a557ebaf07569af1b7f8083962dbd7
our-claude-skills/ourdigital-custom-skills/12-ourdigital-seo-audit/SKILL.md
Andrew Yim 9426787ba6 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>
2025-12-14 02:30:02 +09:00

9.4 KiB
Raw Blame History

name, description, allowed-tools
name description allowed-tools
ourdigital-seo-audit 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. 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:

# 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:

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

python scripts/schema_generator.py --type organization --url https://example.com

Schema Validator

python scripts/schema_validator.py --url https://example.com

Sitemap Validator

python scripts/sitemap_validator.py --url https://example.com/sitemap.xml

Robots.txt Checker

python scripts/robots_checker.py --url https://example.com/robots.txt

Full Audit

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
Reference in New Issue View Git Blame Copy Permalink