Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.
feat: v1.8.0 - Firecrawl extension, backlink analysis, Excel export
Daniel03ec8df0d0ab
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex a06ff97..74b0b84 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "claude-seo",- "version": "1.7.1",+ "version": "1.8.0","description": "Comprehensive SEO analysis skill for Claude Code. Covers technical SEO, content quality (E-E-A-T), schema markup, image optimization, sitemap architecture, AI search optimization (GEO), local SEO (GBP, citations, reviews, map pack), maps intelligence, and strategic planning across all industries.","author": {"name": "AgriciDaniel",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1ae49b3..7a3a719 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).+## [1.8.0] - 2026-03-30++### Added+- **Firecrawl extension**: Full-site crawling, scraping, and site mapping via Firecrawl MCP (`extensions/firecrawl/`)+ - 4 commands: crawl, map, scrape, search+ - JS rendering support for SPA/CSR sites (addresses #11)+ - Cross-skill integration with audit, technical, sitemap, and content skills+ - Self-contained install/uninstall scripts (Bash + PowerShell)+- **Backlink analysis skill**: `skills/seo-backlinks/SKILL.md` with `/seo backlinks` command+ - 7-section analysis: profile overview, anchor text, referring domain quality, toxic links, top pages, competitor gap, new/lost links+ - Backlink health score (0-100) with weighted factors+ - Disavow recommendations with export format+ - Requires DataForSEO extension for live data+- **Backlink quality reference**: `skills/seo/references/backlink-quality.md` with 30 toxic link patterns, anchor text benchmarks by industry+- **Excel export**: `--format xlsx` option in `scripts/google_report.py`+ - Sheets: Summary, Queries, Pages, Indexation (conditional on data available)+ - Navy header styling matching PDF palette, auto-column-width, frozen headers, auto-filter+ - New format options: `xlsx`, `all` (pdf+html+xlsx)+- **Ecosystem cross-links**: AI Marketing Claude added to README and CLAUDE.md ecosystem sections++### Changed+- Sub-skill count: 18 -> 19 (added seo-backlinks)+- Extension count: 2 -> 3 (added Firecrawl)+- Orchestrator routing table updated with `/seo backlinks` and `/seo firecrawl` commands+- Audit orchestration: Firecrawl `map` used for URL discovery when available+- `requirements.txt`: added `openpyxl>=3.1.0` for Excel export+## [1.7.1] - 2026-03-30### Fixeddiff --git a/CLAUDE.md b/CLAUDE.mdindex 043efe8..49ff73e 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -142,10 +142,11 @@ claude-seo/Part of the Claude Code skill family:- [Claude Banana](https://github.com/AgriciDaniel/banana-claude) -- standalone image gen (bundled as extension here)- [Claude Blog](https://github.com/AgriciDaniel/claude-blog) -- companion blog engine, consumes SEO findings+- [AI Marketing Claude](https://github.com/zubair-trabzada/ai-marketing-claude) -- community marketing suite (copy, emails, ads, funnels, CRO)## Key Principles1. **Progressive Disclosure**: Metadata always loaded, instructions on activation, resources on demand2. **Industry Detection**: Auto-detect SaaS, e-commerce, local, publisher, agency3. **Parallel Execution**: Full audits spawn up to 11 subagents simultaneously-4. **Extension System**: DataForSEO MCP for live data, Banana MCP for AI image generation+4. **Extension System**: DataForSEO MCP for live data, Firecrawl MCP for site crawling, Banana MCP for AI image generationdiff --git a/README.md b/README.mdindex 6799594..495b7d0 100644--- a/README.md+++ b/README.md@@ -320,12 +320,14 @@ Claude SEO is part of a family of Claude Code skills that work together:| [Claude SEO](https://github.com/AgriciDaniel/claude-seo) | SEO analysis, audits, schema, GEO | Core -- analyzes sites, generates action plans || [Claude Blog](https://github.com/AgriciDaniel/claude-blog) | Blog writing, optimization, scoring | Companion -- write content optimized by SEO findings || [Claude Banana](https://github.com/AgriciDaniel/banana-claude) | AI image generation via Gemini | Shared -- generates images for SEO assets and blog posts |+| [AI Marketing Claude](https://github.com/zubair-trabzada/ai-marketing-claude) | Copywriting, emails, social, ads, funnels, CRO | Community -- post-audit marketing action from SEO findings |**Workflow example:**-1. `/seo audit https://example.com` -- identify content gaps and image issues-2. `/blog write "target keyword"` -- create SEO-optimized blog posts-3. `/seo image-gen hero "blog topic"` -- generate hero images (banana extension)-4. `/seo geo https://example.com/blog/post` -- optimize for AI citations+1. `/seo audit https://example.com` -- identify content gaps and technical issues+2. `/seo backlinks https://example.com` -- analyze link profile and competitor gaps+3. `/blog write "target keyword"` -- create SEO-optimized blog posts+4. `/seo image-gen hero "blog topic"` -- generate hero images (banana extension)+5. `/seo geo https://example.com/blog/post` -- optimize for AI citations## Documentationdiff --git a/extensions/firecrawl/README.md b/extensions/firecrawl/README.mdnew file mode 100644index 0000000..84ad6b1--- /dev/null+++ b/extensions/firecrawl/README.md@@ -0,0 +1,82 @@+# Firecrawl Extension for Claude SEO++Full-site crawling, scraping, and site mapping powered by [Firecrawl](https://www.firecrawl.dev/). Enables comprehensive site-wide SEO analysis with JavaScript rendering support.++## Prerequisites++- [Claude SEO](https://github.com/AgriciDaniel/claude-seo) installed+- Node.js 20++- Firecrawl API key ([sign up](https://www.firecrawl.dev/app/sign-up) -- free tier: 500 credits/month)++## Installation++### macOS / Linux++```bash+./extensions/firecrawl/install.sh+```++### Windows (PowerShell)++```powershell+.\extensions\firecrawl\install.ps1+```++The installer will prompt for your Firecrawl API key and configure the MCP server automatically.++## Commands++| Command | Purpose | Credits |+|---------|---------|---------|+| `/seo firecrawl crawl <url>` | Full-site crawl with content extraction | 1 per page |+| `/seo firecrawl map <url>` | Discover site structure (URLs only) | 0.5 per URL |+| `/seo firecrawl scrape <url>` | Single-page deep scrape with JS rendering | 1 |+| `/seo firecrawl search <query> <url>` | Search within a site | 1 per result |++## Integration with Claude SEO++When installed, other Claude SEO skills automatically leverage Firecrawl:++- **`/seo audit`**: Uses `map` to discover all pages, then `crawl` for deep analysis+- **`/seo technical`**: Broken link detection across entire site+- **`/seo sitemap`**: Compare XML sitemap vs actual crawlable pages+- **`/seo content`**: Thin content detection at scale++## Cost++| Plan | Credits/month | Price |+|------|--------------|-------|+| Free | 500 | $0 |+| Hobby | 3,000 | $16/mo |+| Standard | 100,000 | $83/mo |+| Growth | 500,000 | $333/mo |++1 credit = 1 page crawled or scraped. Map operations use 0.5 credits per URL.++## Troubleshooting++**MCP not connecting?**+- Check: `cat ~/.claude/settings.json | python3 -m json.tool | grep firecrawl`+- Manual config: See [FIRECRAWL-SETUP.md](docs/FIRECRAWL-SETUP.md)++**Credits exhausted?**+- Check usage: https://www.firecrawl.dev/app+- Upgrade plan or wait for monthly reset++**Site blocking crawls?**+- Some sites block automated crawling via robots.txt or Cloudflare+- Try `scrape` (single page) instead of `crawl` (full site)+- Fall back to `fetch_page.py` for basic HTML retrieval++## Uninstall++```bash+./extensions/firecrawl/uninstall.sh # macOS/Linux+.\extensions\firecrawl\uninstall.ps1 # Windows+```++## Links++- [Firecrawl Documentation](https://docs.firecrawl.dev/)+- [Firecrawl MCP Server](https://www.npmjs.com/package/firecrawl-mcp)+- [Claude SEO](https://github.com/AgriciDaniel/claude-seo)diff --git a/extensions/firecrawl/docs/FIRECRAWL-SETUP.md b/extensions/firecrawl/docs/FIRECRAWL-SETUP.mdnew file mode 100644index 0000000..75d8072--- /dev/null+++ b/extensions/firecrawl/docs/FIRECRAWL-SETUP.md@@ -0,0 +1,59 @@+# Firecrawl Setup Guide++## 1. Get Your API Key++1. Go to [firecrawl.dev/app/sign-up](https://www.firecrawl.dev/app/sign-up)+2. Create a free account (500 credits/month included)+3. Navigate to **API Keys** in the dashboard+4. Copy your API key (starts with `fc-`)++## 2. Run the Installer++The installer handles everything automatically:++```bash+./extensions/firecrawl/install.sh+```++It will prompt for your API key and configure the MCP server.++## 3. Manual MCP Configuration++If the installer fails, add this to `~/.claude/settings.json` manually:++```json+{+ "mcpServers": {+ "firecrawl-mcp": {+ "command": "npx",+ "args": ["-y", "firecrawl-mcp"],+ "env": {+ "FIRECRAWL_API_KEY": "fc-your-api-key-here"+ }+ }+ }+}+```++## 4. Verify Installation++Start Claude Code and try:++```+/seo firecrawl map https://example.com+```++You should see a list of discovered URLs. If you get a "tool not available" error, restart Claude Code to reload MCP servers.++## 5. Understanding Credits++| Operation | Credits Used |+|-----------|-------------|+| `crawl` | 1 per page crawled |+| `scrape` | 1 per page |+| `map` | 0.5 per URL discovered |+| `search` | 1 per result returned |++**Free tier**: 500 credits/month resets on your billing date.++**Tip**: Use `map` first (cheap) to see how many pages a site has, then decide how many to `crawl` (more expensive).diff --git a/extensions/firecrawl/install.ps1 b/extensions/firecrawl/install.ps1new file mode 100644index 0000000..75569c8--- /dev/null+++ b/extensions/firecrawl/install.ps1@@ -0,0 +1,89 @@+# Firecrawl Extension Installer for Claude SEO (Windows)+$ErrorActionPreference = 'Stop'++Write-Host "====================================" -ForegroundColor Cyan+Write-Host " Firecrawl Extension - Installer" -ForegroundColor Cyan+Write-Host " For Claude SEO" -ForegroundColor Cyan+Write-Host "====================================" -ForegroundColor Cyan+Write-Host ""++$SkillDir = "$env:USERPROFILE\.claude\skills\seo-firecrawl"+$SeoSkillDir = "$env:USERPROFILE\.claude\skills\seo"+$SettingsFile = "$env:USERPROFILE\.claude\settings.json"++# Check prerequisites+if (-not (Test-Path $SeoSkillDir)) {+ Write-Host "x Claude SEO is not installed." -ForegroundColor Red+ Write-Host " Install it first: irm https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.ps1 | iex"+ exit 1+}+Write-Host "v Claude SEO detected" -ForegroundColor Green++$nodeVersion = (node -v 2>$null) -replace 'v',''+if (-not $nodeVersion) {+ Write-Host "x Node.js is required but not installed." -ForegroundColor Red+ exit 1+}+$major = [int]($nodeVersion -split '\.')[0]+if ($major -lt 20) {+ Write-Host "x Node.js 20+ required (found v$nodeVersion)." -ForegroundColor Red+ exit 1+}+Write-Host "v Node.js v$nodeVersion detected" -ForegroundColor Green++# Prompt for API key+Write-Host ""+Write-Host "Firecrawl API key required." -ForegroundColor Yellow+Write-Host "Sign up at: https://www.firecrawl.dev/app/sign-up"+Write-Host "Free tier: 500 credits/month"+Write-Host ""++$apiKey = Read-Host "Firecrawl API key" -AsSecureString+$apiKeyPlain = [Runtime.InteropServices.Marshal]::PtrToStringAuto(+ [Runtime.InteropServices.Marshal]::SecureStringToBSTR($apiKey))+if ([string]::IsNullOrWhiteSpace($apiKeyPlain)) {+ Write-Host "x API key cannot be empty." -ForegroundColor Red+ exit 1+}++# Determine source directory+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path+$SourceDir = $null+if (Test-Path "$ScriptDir\skills\seo-firecrawl\SKILL.md") {+ $SourceDir = $ScriptDir+} elseif (Test-Path "$ScriptDir\extensions\firecrawl\skills\seo-firecrawl\SKILL.md") {+ $SourceDir = "$ScriptDir\extensions\firecrawl"+} else {+ Write-Host "x Cannot find extension source files." -ForegroundColor Red+ exit 1+}++# Install skill+Write-Host ""+Write-Host "=> Installing Firecrawl skill..." -ForegroundColor Yellow+New-Item -ItemType Directory -Force -Path $SkillDir | Out-Null+Copy-Item "$SourceDir\skills\seo-firecrawl\SKILL.md" "$SkillDir\SKILL.md" -Force++# Configure MCP server+Write-Host "=> Configuring MCP server..." -ForegroundColor Yellow+$settingsContent = if (Test-Path $SettingsFile) { Get-Content $SettingsFile -Raw | ConvertFrom-Json } else { @{} }+if (-not $settingsContent.mcpServers) { $settingsContent | Add-Member -NotePropertyName mcpServers -NotePropertyValue @{} -Force }+$settingsContent.mcpServers | Add-Member -NotePropertyName 'firecrawl-mcp' -NotePropertyValue @{+ command = 'npx'+ args = @('-y', 'firecrawl-mcp')+ env = @{ FIRECRAWL_API_KEY = $apiKeyPlain }+} -Force+$settingsContent | ConvertTo-Json -Depth 10 | Set-Content $SettingsFile -Encoding UTF8+Write-Host " v MCP server configured" -ForegroundColor Green++# Pre-warm+Write-Host "=> Pre-downloading firecrawl-mcp..." -ForegroundColor Yellow+npx -y firecrawl-mcp --help 2>$null | Out-Null++Write-Host ""+Write-Host "v Firecrawl extension installed!" -ForegroundColor Green+Write-Host ""+Write-Host "Usage:"+Write-Host " /seo firecrawl crawl https://example.com"+Write-Host " /seo firecrawl map https://example.com"+Write-Host " /seo firecrawl scrape https://example.com/page"diff --git a/extensions/firecrawl/install.sh b/extensions/firecrawl/install.shnew file mode 100644index 0000000..c7d6536--- /dev/null+++ b/extensions/firecrawl/install.sh@@ -0,0 +1,141 @@+#!/usr/bin/env bash+set -euo pipefail++# Firecrawl Extension Installer for Claude SEO+# Wraps everything in main() to prevent partial execution on network failure++main() {+ SKILL_DIR="${HOME}/.claude/skills/seo-firecrawl"+ AGENT_DIR="${HOME}/.claude/agents"+ SEO_SKILL_DIR="${HOME}/.claude/skills/seo"+ SETTINGS_FILE="${HOME}/.claude/settings.json"++ echo "════════════════════════════════════════"+ echo "║ Firecrawl Extension - Installer ║"+ echo "║ For Claude SEO ║"+ echo "════════════════════════════════════════"+ echo ""++ # Check prerequisites+ if [ ! -d "${SEO_SKILL_DIR}" ]; then+ echo "x Claude SEO is not installed."+ echo " Install it first: curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh | bash"+ exit 1+ fi+ echo "v Claude SEO detected"++ if ! command -v node >/dev/null 2>&1; then+ echo "x Node.js is required but not installed."+ echo " Install Node.js 20+: https://nodejs.org/"+ exit 1+ fi++ NODE_VERSION=$(node -v | sed 's/v//' | cut -d. -f1)+ if [ "${NODE_VERSION}" -lt 20 ]; then+ echo "x Node.js 20+ required (found v${NODE_VERSION})."+ echo " Update: https://nodejs.org/"+ exit 1+ fi+ echo "v Node.js v$(node -v | sed 's/v//') detected"++ if ! command -v npx >/dev/null 2>&1; then+ echo "x npx is required but not found (comes with npm)."+ exit 1+ fi+ echo "v npx detected"++ # Prompt for credentials+ echo ""+ echo "Firecrawl API key required."+ echo "Sign up at: https://www.firecrawl.dev/app/sign-up"+ echo "Free tier: 500 credits/month"+ echo ""++ read -rsp "Firecrawl API key: " FIRECRAWL_API_KEY+ echo ""+ if [ -z "${FIRECRAWL_API_KEY}" ]; then+ echo "x API key cannot be empty."+ exit 1+ fi++ # Determine script directory (works for both ./install.sh and curl|bash)+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"++ # Check if running from repo or standalone+ if [ -f "${SCRIPT_DIR}/skills/seo-firecrawl/SKILL.md" ]; then+ SOURCE_DIR="${SCRIPT_DIR}"+ elif [ -f "${SCRIPT_DIR}/extensions/firecrawl/skills/seo-firecrawl/SKILL.md" ]; then+ SOURCE_DIR="${SCRIPT_DIR}/extensions/firecrawl"+ else+ echo "x Cannot find extension source files."+ echo " Run this script from the claude-seo repo: ./extensions/firecrawl/install.sh"+ exit 1+ fi++ # Install skill+ echo ""+ echo "-> Installing Firecrawl skill..."+ mkdir -p "${SKILL_DIR}"+ cp "${SOURCE_DIR}/skills/seo-firecrawl/SKILL.md" "${SKILL_DIR}/SKILL.md"++ # Merge MCP config into settings.json+ echo "-> Configuring MCP server..."++ python3 -c "+import json, os, sys++settings_path = '${SETTINGS_FILE}'+api_key = '''${FIRECRAWL_API_KEY}'''++# Read existing settings or create new+if os.path.exists(settings_path):+ with open(settings_path, 'r') as f:+ settings = json.load(f)+else:+ settings = {}++# Ensure mcpServers key exists+if 'mcpServers' not in settings:+ settings['mcpServers'] = {}++# Add Firecrawl server config+settings['mcpServers']['firecrawl-mcp'] = {+ 'command': 'npx',+ 'args': ['-y', 'firecrawl-mcp'],+ 'env': {+ 'FIRECRAWL_API_KEY': api_key+ }+}++# Write back+os.makedirs(os.path.dirname(settings_path), exist_ok=True)+with open(settings_path, 'w') as f:+ json.dump(settings, f, indent=2)++print(' v MCP server configured in settings.json')+" || {+ echo " Warning: Could not auto-configure MCP server."+ echo " Add the firecrawl-mcp server manually to ~/.claude/settings.json"+ echo " See: extensions/firecrawl/docs/FIRECRAWL-SETUP.md"+ }++ # Pre-warm npx package+ echo "-> Pre-downloading firecrawl-mcp..."+ npx -y firecrawl-mcp --help >/dev/null 2>&1 || true++ echo ""+ echo "v Firecrawl extension installed successfully!"+ echo ""+ echo "Usage:"+ echo " 1. Start Claude Code: claude"+ echo " 2. Run commands:"+ echo " /seo firecrawl crawl https://example.com"+ echo " /seo firecrawl map https://example.com"+ echo " /seo firecrawl scrape https://example.com/page"+ echo " /seo firecrawl search \"query\" https://example.com"+ echo ""+ echo "Documentation: extensions/firecrawl/README.md"+ echo "To uninstall: ./extensions/firecrawl/uninstall.sh"+}++main "$@"diff --git a/extensions/firecrawl/skills/seo-firecrawl/SKILL.md b/extensions/firecrawl/skills/seo-firecrawl/SKILL.mdnew file mode 100644index 0000000..e3e1388--- /dev/null+++ b/extensions/firecrawl/skills/seo-firecrawl/SKILL.md@@ -0,0 +1,209 @@+---+name: seo-firecrawl+description: >+ Full-site crawling, scraping, and site mapping via Firecrawl MCP.+ Use when user says "crawl site", "map site", "full crawl",+ "find all pages", "broken links", "site structure",+ "discover pages", "JS rendering", or needs site-wide analysis.+user-invokable: true+argument-hint: "[command] <url>"+license: MIT+allowed-tools:+ - Read+ - Grep+ - Glob+ - Bash+ - WebFetch+ - Write+compatibility: "Requires Firecrawl MCP server"+metadata:+ author: AgriciDaniel+ version: "1.8.0"+ category: seo+---++# Firecrawl Extension for Claude SEO++This skill requires the Firecrawl extension to be installed:+```bash+./extensions/firecrawl/install.sh+```++**Check availability:** Before using any Firecrawl tool, verify the MCP server+is connected by checking if `firecrawl_scrape` or any Firecrawl tool+is available. If tools are not available, inform the user the extension is not+installed and provide install instructions.++## Quick Reference++| Command | Purpose |+|---------|---------|+| `/seo firecrawl crawl <url>` | Full-site crawl with content extraction |+| `/seo firecrawl map <url>` | Discover site structure (URLs only, fast) |+| `/seo firecrawl scrape <url>` | Single-page scrape with JS rendering |+| `/seo firecrawl search <query> <url>` | Search within a crawled site |++## Commands++### crawl -- Full-Site Crawl++Crawl an entire website starting from the given URL. Returns page content,+metadata, and links for all discovered pages.++**MCP Tool:** `firecrawl_crawl`++**Parameters:**+- `url` (required): Starting URL to crawl+- `limit`: Max pages to crawl (default: 100, max: 500)+- `maxDepth`: Max link depth from start URL (default: 3)+- `includePaths`: Array of glob patterns to include (e.g., `["/blog/*"]`)+- `excludePaths`: Array of glob patterns to exclude (e.g., `["/admin/*", "/api/*"]`)+- `scrapeOptions.formats`: Output formats -- `["markdown", "html", "links"]`++**SEO Usage Patterns:**+1. **Comprehensive audit crawl**: Crawl full site, extract all pages for subagent analysis+2. **Section-focused crawl**: Use `includePaths` to audit only `/blog/*` or `/products/*`+3. **Broken link detection**: Crawl with `["links"]` format, check all hrefs for 404s+4. **Content inventory**: Extract all page titles, meta descriptions, H1s at scale+5. **SPA/JS-rendered sites**: Firecrawl renders JavaScript, solving the Issue #11 problem++**Example orchestration for `/seo audit`:**+```+1. firecrawl_map(url) -> get all URLs (fast, no content)+2. Filter to top 50 most important pages (homepage, key sections)+3. firecrawl_crawl(url, limit=50) -> get full content+4. Feed content to seo-technical, seo-content, seo-schema agents+```++**Cost awareness:**+- Free tier: 500 credits/month+- 1 credit = 1 page crawled or scraped+- Map operations are cheaper (0.5 credits per URL discovered)+- Always inform user of estimated credit usage before large crawls++### map -- Site Structure Discovery++Discover all URLs on a website without fetching content. Fast and credit-efficient.++**MCP Tool:** `firecrawl_map`++**Parameters:**+- `url` (required): Website URL to map+- `limit`: Max URLs to discover (default: 5000)+- `search`: Optional search term to filter URLs++**SEO Usage Patterns:**+1. **Sitemap comparison**: Map site, compare discovered URLs vs XML sitemap+2. **Orphan page detection**: URLs in sitemap but not linked from any page+3. **Crawl budget analysis**: Total indexable pages vs pages linked from homepage+4. **URL pattern analysis**: Identify URL structure patterns, duplicates, parameter bloat+5. **Pre-audit discovery**: Run map first, then targeted crawl on key sections++**Output:** Array of URLs. Present as:+```+Site: example.com+Pages discovered: 342++URL Pattern Breakdown:+ /blog/* - 128 pages (37%)+ /products/* - 89 pages (26%)+ /category/* - 45 pages (13%)+ /pages/* - 32 pages (9%)+ / (root pages) - 48 pages (14%)+```++### scrape -- Single-Page Deep Scrape++Scrape a single page with full JavaScript rendering. More thorough than+`fetch_page.py` because it executes JS and waits for dynamic content.++**MCP Tool:** `firecrawl_scrape`++**Parameters:**+- `url` (required): Page URL to scrape+- `formats`: Output formats -- `["markdown", "html", "links", "screenshot"]`+- `onlyMainContent`: Strip nav/footer/sidebar (default: true)+- `waitFor`: CSS selector or milliseconds to wait for content+- `timeout`: Request timeout in ms (default: 30000)+- `actions`: Browser actions before scraping (click, scroll, wait)++**SEO Usage Patterns:**+1. **SPA content extraction**: Scrape JS-rendered React/Vue/Angular pages+2. **Dynamic content audit**: Pages with lazy-loaded content below the fold+3. **Paywall/login detection**: Identify content behind authentication walls+4. **Main content extraction**: Use `onlyMainContent` for clean E-E-A-T analysis+5. **Screenshot capture**: Use `screenshot` format for visual analysis++**When to use scrape vs fetch_page.py:**+| Scenario | Use |+|----------|-----|+| Static HTML page | `fetch_page.py` (no API cost) |+| JS-rendered SPA | `firecrawl_scrape` (renders JS) |+| Need response headers | `fetch_page.py` (returns headers) |+| Need clean markdown | `firecrawl_scrape` (better extraction) |+| Rate-limited/blocked | `firecrawl_scrape` (handles anti-bot) |++### search -- Site-Scoped Search++Search within a website for specific content. Useful for finding pages+related to a topic without crawling everything.++**MCP Tool:** `firecrawl_search`++**Parameters:**+- `query` (required): Search query+- `url` (required): Website to search within+- `limit`: Max results (default: 10)+- `scrapeOptions.formats`: Output format for matched pages++**SEO Usage Patterns:**+1. **Content gap validation**: Search for a keyword on the site to check if content exists+2. **Internal linking opportunities**: Find pages mentioning a topic that could link to each other+3. **Duplicate content detection**: Search for key phrases to find near-duplicates+4. **Competitor content research**: Search competitor site for specific topics++## Cross-Skill Integration++### With seo-audit (full audit)+When Firecrawl is available during `/seo audit`:+1. Use `firecrawl_map` to discover all site URLs+2. Compare with XML sitemap (seo-sitemap) to find orphan/missing pages+3. Select top pages for deep analysis+4. Feed crawled content to all subagents (technical, content, schema, geo)+5. Report total crawlable pages, URL patterns, and crawl depth++### With seo-technical+- Broken link detection: crawl all internal links, check for 404s+- Redirect chain mapping: follow all redirects, flag chains > 2 hops+- Mixed content detection: check HTTP resources on HTTPS pages+- Canonical verification: compare canonical URLs with actual URLs++### With seo-sitemap+- Sitemap coverage: % of crawled pages present in sitemap+- Orphan pages: pages found by crawl but missing from sitemap+- Stale sitemap entries: URLs in sitemap that return 404/410++### With seo-content+- Content extraction: feed clean markdown to E-E-A-T analysis+- Thin content detection: identify pages with < 300 words at scale+- Duplicate content: compare content across pages for near-duplicates++### With seo-schema+- Schema extraction: pull JSON-LD from all crawled pages+- Schema coverage: % of pages with structured data+- Schema validation: batch-validate extracted schemas++## Error Handling++| Error | Cause | Resolution |+|-------|-------|-----------|+| `FIRECRAWL_API_KEY not set` | MCP not configured | Run `./extensions/firecrawl/install.sh` |+| `402 Payment Required` | Credits exhausted | Check usage at firecrawl.dev/app, upgrade plan |+| `429 Too Many Requests` | Rate limited | Wait 60s, reduce crawl concurrency |+| `408 Timeout` | Page too slow to render | Increase `timeout`, try without JS rendering |+| `403 Forbidden` | Site blocks crawling | Check robots.txt, may need to skip this site |++**Graceful fallback:** If Firecrawl is unavailable, inform the user and suggest:+1. Use `fetch_page.py` for single-page analysis (no API cost)+2. Use `WebFetch` tool for basic HTML retrieval+3. Install Firecrawl: `./extensions/firecrawl/install.sh`diff --git a/extensions/firecrawl/uninstall.ps1 b/extensions/firecrawl/uninstall.ps1new file mode 100644index 0000000..4b56515--- /dev/null+++ b/extensions/firecrawl/uninstall.ps1@@ -0,0 +1,25 @@+# Firecrawl Extension Uninstaller for Claude SEO (Windows)+$ErrorActionPreference = 'Stop'++Write-Host "Removing Firecrawl extension..." -ForegroundColor Yellow++$SkillDir = "$env:USERPROFILE\.claude\skills\seo-firecrawl"+$SettingsFile = "$env:USERPROFILE\.claude\settings.json"++if (Test-Path $SkillDir) {+ Remove-Item -Recurse -Force $SkillDir+ Write-Host "v Removed skill files" -ForegroundColor Green+}++if (Test-Path $SettingsFile) {+ $settings = Get-Content $SettingsFile -Raw | ConvertFrom-Json+ if ($settings.mcpServers.'firecrawl-mcp') {+ $settings.mcpServers.PSObject.Properties.Remove('firecrawl-mcp')+ $settings | ConvertTo-Json -Depth 10 | Set-Content $SettingsFile -Encoding UTF8+ Write-Host "v Removed MCP server from settings.json" -ForegroundColor Green+ }+}++Write-Host ""+Write-Host "v Firecrawl extension uninstalled." -ForegroundColor Green+Write-Host " Core Claude SEO skills are unchanged."diff --git a/extensions/firecrawl/uninstall.sh b/extensions/firecrawl/uninstall.shnew file mode 100644index 0000000..8b0fe02--- /dev/null+++ b/extensions/firecrawl/uninstall.sh@@ -0,0 +1,32 @@+#!/usr/bin/env bash+set -euo pipefail++echo "Removing Firecrawl extension..."++# Remove skill directory+rm -rf "${HOME}/.claude/skills/seo-firecrawl"+echo "v Removed skill files"++# Remove MCP entry from settings.json+SETTINGS_FILE="${HOME}/.claude/settings.json"+if [ -f "${SETTINGS_FILE}" ]; then+ python3 -c "+import json, os++settings_path = '${SETTINGS_FILE}'+with open(settings_path, 'r') as f:+ settings = json.load(f)++if 'mcpServers' in settings and 'firecrawl-mcp' in settings['mcpServers']:+ del settings['mcpServers']['firecrawl-mcp']+ with open(settings_path, 'w') as f:+ json.dump(settings, f, indent=2)+ print('v Removed MCP server from settings.json')+else:+ print(' MCP server not found in settings.json (already removed)')+" || echo " Warning: Could not update settings.json automatically."+fi++echo ""+echo "v Firecrawl extension uninstalled."+echo " Core Claude SEO skills are unchanged."diff --git a/install.ps1 b/install.ps1index 9b1cc0d..7e0092f 100644--- a/install.ps1+++ b/install.ps1@@ -87,7 +87,7 @@ $AgentDir = "$env:USERPROFILE\.claude\agents"$RepoUrl = "https://github.com/AgriciDaniel/claude-seo"# Pin to a specific release tag to prevent silent updates from main.# Override: $env:CLAUDE_SEO_TAG = 'main'; .\install.ps1-$RepoTag = if ($env:CLAUDE_SEO_TAG) { $env:CLAUDE_SEO_TAG } else { 'v1.7.1' }+$RepoTag = if ($env:CLAUDE_SEO_TAG) { $env:CLAUDE_SEO_TAG } else { 'v1.8.0' }# Create directoriesNew-Item -ItemType Directory -Force -Path $SkillDir | Out-Nulldiff --git a/install.sh b/install.shindex f520888..640e3f3 100755--- a/install.sh+++ b/install.sh@@ -10,7 +10,7 @@ main() {REPO_URL="https://github.com/AgriciDaniel/claude-seo"# Pin to a specific release tag to prevent silent updates from main.# Override: CLAUDE_SEO_TAG=main bash install.sh- REPO_TAG="${CLAUDE_SEO_TAG:-v1.7.1}"+ REPO_TAG="${CLAUDE_SEO_TAG:-v1.8.0}"echo "════════════════════════════════════════"echo "║ Claude SEO - Installer ║"diff --git a/requirements.txt b/requirements.txtindex eb32bec..f88cf0e 100644--- a/requirements.txt+++ b/requirements.txt@@ -10,9 +10,10 @@ Pillow>=12.1.0,<13.0.0 # CVE-2025-48379 fixurllib3>=2.6.3,<3.0.0 # CRITICAL: CVE-2026-21441 (CVSS 8.9), CVE-2025-66418validators>=0.22.0,<1.0.0 # No known CVEs-# Report generation (for seo-google PDF reports)+# Report generation (for seo-google PDF/Excel reports)matplotlib>=3.8.0,<4.0.0 # No known CVEsweasyprint>=61.0,<70.0 # No known CVEs+openpyxl>=3.1.0,<4.0.0 # No known CVEs (Excel export)# Google API dependencies (for seo-google skill)google-api-python-client>=2.100.0,<3.0.0 # No known CVEsdiff --git a/scripts/google_report.py b/scripts/google_report.pyindex 1d9b5b3..bdcda82 100644--- a/scripts/google_report.py+++ b/scripts/google_report.py@@ -2136,13 +2136,13 @@ def generate_report(report_type, data, domain, output_dir, output_format="pdf"):safe_domain = domain.replace(":", "_").replace("/", "_")base_name = f"Google-SEO-Report-{safe_domain}-{report_type}"- if output_format in ("html", "both"):+ if output_format in ("html", "both", "all"):html_path = output_dir / f"{base_name}.html"with open(html_path, "w", encoding="utf-8") as f:f.write(html_content)result["files"].append(str(html_path))- if output_format in ("pdf", "both"):+ if output_format in ("pdf", "both", "all"):pdf_path = output_dir / f"{base_name}.pdf"try:HTML(string=html_content).write_pdf(str(pdf_path))@@ -2154,6 +2154,11 @@ def generate_report(report_type, data, domain, output_dir, output_format="pdf"):except Exception as e:result["error"] = f"PDF generation failed: {e}"+ if output_format in ("xlsx", "all"):+ xlsx_path = generate_xlsx(data, domain, report_type, output_dir)+ if xlsx_path:+ result["files"].append(xlsx_path)+return result@@ -2208,6 +2213,189 @@ def _review_pdf(pdf_path: str, html_content: str) -> dict:return review+# ─── XLSX Export ──────────────────────────────────────────────────────────────++def generate_xlsx(data, domain, report_type, output_dir):+ """Generate Excel workbook from audit data.++ Returns path to generated .xlsx file, or None if openpyxl unavailable.+ """+ try:+ from openpyxl import Workbook+ from openpyxl.styles import Font, PatternFill, Alignment, Border, Side+ from openpyxl.utils import get_column_letter+ except ImportError:+ print("Warning: openpyxl not installed. Skipping xlsx. Install: pip install openpyxl", file=sys.stderr)+ return None++ wb = Workbook()+ output_dir = Path(output_dir)++ # Brand colors for Excel+ navy_fill = PatternFill(start_color="1E3A5F", end_color="1E3A5F", fill_type="solid")+ cream_fill = PatternFill(start_color="FAF9F7", end_color="FAF9F7", fill_type="solid")+ green_fill = PatternFill(start_color="D4EDDA", end_color="D4EDDA", fill_type="solid")+ amber_fill = PatternFill(start_color="FFF3CD", end_color="FFF3CD", fill_type="solid")+ red_fill = PatternFill(start_color="F8D7DA", end_color="F8D7DA", fill_type="solid")+ header_font = Font(name="Calibri", bold=True, color="FFFFFF", size=11)+ body_font = Font(name="Calibri", size=10)+ thin_border = Border(+ left=Side(style="thin", color="D6D3CC"),+ right=Side(style="thin", color="D6D3CC"),+ top=Side(style="thin", color="D6D3CC"),+ bottom=Side(style="thin", color="D6D3CC"),+ )++ def _style_header(ws, row=1):+ """Apply navy header styling to the first row."""+ for cell in ws[row]:+ cell.font = header_font+ cell.fill = navy_fill+ cell.alignment = Alignment(horizontal="center", vertical="center")+ cell.border = thin_border++ def _auto_width(ws):+ """Auto-fit column widths based on content."""+ for col_cells in ws.columns:+ max_len = 0+ col_letter = get_column_letter(col_cells[0].column)+ for cell in col_cells:+ if cell.value:+ max_len = max(max_len, len(str(cell.value)))+ ws.column_dimensions[col_letter].width = min(max_len + 4, 60)++ def _severity_fill(severity):+ """Return fill color based on severity string."""+ s = str(severity).lower()+ if s in ("critical", "fail", "high"):+ return red_fill+ if s in ("warning", "warn", "medium"):+ return amber_fill+ if s in ("pass", "good", "low"):+ return green_fill+ return cream_fill++ # ── Summary Sheet ─────────────────────────────────────────────────────────+ ws = wb.active+ ws.title = "Summary"+ ws.append(["Google SEO Report", "", ""])+ ws.append(["Domain", domain])+ ws.append(["Report Type", report_type])+ ws.append(["Generated", datetime.now().strftime("%Y-%m-%d %H:%M")])+ ws.append([])++ # Add scores if available+ if report_type in ("cwv-audit", "full"):+ psi = data.get("psi", data)+ mobile = psi.get("psi", {}).get("mobile", psi) if isinstance(psi, dict) else {}+ scores = mobile.get("lighthouse_scores", {}) if isinstance(mobile, dict) else {}+ if scores:+ ws.append(["Lighthouse Scores", ""])+ ws.append(["Category", "Score"])+ _style_header(ws, ws.max_row)+ for cat in ["performance", "accessibility", "best_practices", "seo"]:+ val = scores.get(cat)+ if val is not None:+ row_num = ws.max_row + 1+ ws.append([cat.replace("_", " ").title(), int(val * 100) if val <= 1 else val])+ ws.cell(row=row_num, column=2).fill = _severity_fill(+ "pass" if (val * 100 if val <= 1 else val) >= 90+ else "warning" if (val * 100 if val <= 1 else val) >= 50+ else "fail"+ )+ ws.append([])++ # CWV metrics+ if report_type in ("cwv-audit", "full"):+ crux = data.get("crux", {})+ metrics = crux.get("metrics", {}) if isinstance(crux, dict) else {}+ if metrics:+ ws.append(["Core Web Vitals (Field Data)", ""])+ ws.append(["Metric", "Value", "Rating"])+ _style_header(ws, ws.max_row)+ for metric_name, metric_data in metrics.items():+ if isinstance(metric_data, dict):+ p75 = metric_data.get("percentile_p75", metric_data.get("p75", ""))+ rating = metric_data.get("category", "")+ ws.append([metric_name, p75, rating])+ ws.append([])++ _auto_width(ws)++ # ── GSC Queries Sheet ─────────────────────────────────────────────────────+ gsc = data.get("gsc", {})+ queries = gsc.get("queries", gsc.get("rows", []))+ if queries and isinstance(queries, list):+ ws2 = wb.create_sheet("Queries")+ ws2.append(["Query", "Clicks", "Impressions", "CTR", "Position"])+ _style_header(ws2)+ for row_data in queries[:500]:+ if isinstance(row_data, dict):+ keys = row_data.get("keys", [])+ query = keys[0] if keys else row_data.get("query", "")+ ws2.append([+ query,+ row_data.get("clicks", 0),+ row_data.get("impressions", 0),+ f"{row_data.get('ctr', 0):.2%}" if isinstance(row_data.get("ctr"), (int, float)) else str(row_data.get("ctr", "")),+ round(row_data.get("position", 0), 1) if isinstance(row_data.get("position"), (int, float)) else row_data.get("position", ""),+ ])+ ws2.auto_filter.ref = f"A1:E{ws2.max_row}"+ ws2.freeze_panes = "A2"+ _auto_width(ws2)++ # ── GSC Pages Sheet ───────────────────────────────────────────────────────+ pages = gsc.get("pages", [])+ if pages and isinstance(pages, list):+ ws3 = wb.create_sheet("Pages")+ ws3.append(["Page", "Clicks", "Impressions", "CTR", "Position"])+ _style_header(ws3)+ for row_data in pages[:500]:+ if isinstance(row_data, dict):+ keys = row_data.get("keys", [])+ page = keys[0] if keys else row_data.get("page", "")+ ws3.append([+ page,+ row_data.get("clicks", 0),+ row_data.get("impressions", 0),+ f"{row_data.get('ctr', 0):.2%}" if isinstance(row_data.get("ctr"), (int, float)) else str(row_data.get("ctr", "")),+ round(row_data.get("position", 0), 1) if isinstance(row_data.get("position"), (int, float)) else row_data.get("position", ""),+ ])+ ws3.auto_filter.ref = f"A1:E{ws3.max_row}"+ ws3.freeze_panes = "A2"+ _auto_width(ws3)++ # ── Indexation Sheet ──────────────────────────────────────────────────────+ inspection = data.get("inspection", {})+ results = inspection.get("results", [])+ if results and isinstance(results, list):+ ws4 = wb.create_sheet("Indexation")+ ws4.append(["URL", "Verdict", "Coverage State", "Indexing State", "Crawled As", "Last Crawl"])+ _style_header(ws4)+ for item in results[:500]:+ if isinstance(item, dict):+ result_data = item.get("inspectionResult", item)+ idx = result_data.get("indexStatusResult", {})+ ws4.append([+ item.get("url", result_data.get("inspectedUrl", "")),+ idx.get("verdict", ""),+ idx.get("coverageState", ""),+ idx.get("indexingState", ""),+ idx.get("crawledAs", ""),+ idx.get("lastCrawlTime", ""),+ ])+ ws4.auto_filter.ref = f"A1:F{ws4.max_row}"+ ws4.freeze_panes = "A2"+ _auto_width(ws4)++ # ── Save ──────────────────────────────────────────────────────────────────+ timestamp = datetime.now().strftime("%Y%m%d-%H%M")+ filename = f"Google-SEO-Report-{domain}-{timestamp}.xlsx"+ filepath = output_dir / filename+ wb.save(filepath)+ return str(filepath)++# ─── CLI ─────────────────────────────────────────────────────────────────────def main():@@ -2225,9 +2413,9 @@ def main():parser.add_argument("--output-dir", "-o", default=".", help="Output directory (default: current)")parser.add_argument("--format", "-f",- choices=["pdf", "html", "both"],+ choices=["pdf", "html", "xlsx", "both", "all"],default="pdf",- help="Output format (default: pdf)",+ help="Output format: pdf, html, xlsx, both (pdf+html), all (pdf+html+xlsx)",)parser.add_argument("--json", "-j", action="store_true", help="Output metadata as JSON")diff --git a/skills/seo-backlinks/SKILL.md b/skills/seo-backlinks/SKILL.mdnew file mode 100644index 0000000..13a40852--- /dev/null+++ b/skills/seo-backlinks/SKILL.md@@ -0,0 +1,217 @@+---+name: seo-backlinks+description: >+ Backlink profile analysis: referring domains, anchor text distribution,+ toxic link detection, competitor gap analysis. Requires DataForSEO extension.+ Use when user says "backlinks", "link profile", "referring domains",+ "anchor text", "toxic links", "link gap", "link building",+ "disavow", or "backlink audit".+user-invokable: true+argument-hint: "<url>"+license: MIT+allowed-tools:+ - Read+ - Grep+ - Glob+ - Bash+ - WebFetch+ - Write+compatibility: "Requires DataForSEO MCP server (extension)"+metadata:+ author: AgriciDaniel+ version: "1.8.0"+ category: seo+---++# Backlink Profile Analysis++This skill requires the DataForSEO extension:+```bash+./extensions/dataforseo/install.sh+```++**Check availability:** Before using backlink tools, verify the DataForSEO MCP server+is connected by checking if `dataforseo_backlinks_summary` or similar tools are available.+If unavailable, inform the user and provide install instructions.++## Quick Reference++| Command | Purpose |+|---------|---------|+| `/seo backlinks <url>` | Full backlink profile analysis |+| `/seo backlinks gap <url1> <url2>` | Competitor backlink gap analysis |+| `/seo backlinks toxic <url>` | Toxic link detection and disavow recommendations |+| `/seo backlinks new <url>` | New and lost backlinks (recent changes) |++## Analysis Framework++When analyzing a backlink profile, produce all 7 sections below.++### 1. Profile Overview++Use `dataforseo_backlinks_summary` to get:+- Total backlinks and referring domains+- Domain rank / authority score+- Follow vs nofollow ratio+- Historical trend (growing, stable, or declining)++**Scoring:**++| Metric | Good | Warning | Critical |+|--------|------|---------|----------|+| Referring domains | >100 | 20-100 | <20 |+| Follow ratio | >60% | 40-60% | <40% |+| Domain diversity | No single domain >5% | 1 domain >10% | 1 domain >25% |+| Trend | Growing or stable | Slow decline | Rapid decline (>20%/quarter) |++### 2. Anchor Text Distribution++Use `dataforseo_backlinks_anchors` to analyze anchor text patterns.++**Healthy distribution benchmarks:**++| Anchor Type | Target Range | Over-Optimization Signal |+|-------------|-------------|-------------------------|+| Branded (company/domain name) | 30-50% | <15% |+| URL/naked link | 15-25% | N/A |+| Generic ("click here", "learn more") | 10-20% | N/A |+| Exact match keyword | 3-10% | >15% |+| Partial match keyword | 5-15% | >25% |+| Long-tail / natural | 5-15% | N/A |++Flag if exact-match anchors exceed 15% -- this is a Google Penguin risk signal.++### 3. Referring Domain Quality++Use `dataforseo_backlinks_referring_domains` to assess link quality.++Analyze:+- **TLD distribution**: .edu, .gov, .org = high authority. Excessive .xyz, .info = low quality+- **Country distribution**: Match target market. 80%+ from irrelevant countries = PBN signal+- **Language distribution**: Should match site language. Foreign-language links can be spam+- **Domain rank distribution**: Healthy profiles have links from all authority tiers+- **Follow/nofollow per domain**: Sites that only nofollow = limited SEO value++### 4. Toxic Link Detection++Identify potentially harmful backlinks using these patterns:++**High-risk indicators (flag immediately):**+- Links from known PBN (Private Blog Network) domains+- Unnatural anchor text patterns (100% exact match from a domain)+- Links from penalized or deindexed domains+- Mass directory submissions (50+ directory links)+- Comment spam links (forum/blog comment backlinks at scale)+- Link farms (sites with 10K+ outbound links per page)+- Foreign-language links to English sites (unless intentional)+- Paid link patterns (footer/sidebar links across all pages of a domain)++**Medium-risk indicators (review manually):**+- Links from unrelated niches+- Reciprocal link patterns (A links to B, B links to A)+- Links from thin content pages (<100 words)+- Excessive links from a single domain (>50 backlinks from 1 domain)++**Output:**+```+Toxic Link Report+=================+Total backlinks analyzed: X+Potentially toxic: Y (Z%)++High Risk (recommend disavow):+ [list with domain, reason, anchor text]++Medium Risk (review manually):+ [list with domain, reason, anchor text]+```++### 5. Top Pages by Backlinks++Use `dataforseo_backlinks_backlinks` with target type "page" to find:+- Which pages attract the most backlinks+- Pages with high-authority links (link magnets)+- Pages with zero backlinks (internal linking opportunities)+- 404 pages with backlinks (redirect opportunities to reclaim link equity)++### 6. Competitor Gap Analysis++For `/seo backlinks gap <url1> <url2>`:++Use `dataforseo_backlinks_referring_domains` for both domains and compare:+- Domains linking to competitor but NOT to target = link building opportunities+- Domains linking to both = validate existing relationships+- Domains linking only to target = competitive advantage++**Output:**+```+Competitor Gap: example.com vs competitor.com+=============================================+Competitor has links from X domains you don't+You have links from Y domains competitor doesn't++Top 20 Link Building Opportunities:+ [domain, authority, anchor used for competitor, contact suggestion]+```++### 7. New and Lost Backlinks++Use `dataforseo_backlinks_backlinks` with date filters to track:+- New backlinks in last 30/60/90 days+- Lost backlinks in last 30/60/90 days+- Link velocity (new per month trend)++**Red flags:**+- Sudden spike in new links (possible negative SEO attack)+- Sudden loss of many links (site penalty or content removal)+- Declining velocity over 3+ months (content not attracting links)++## Backlink Health Score++Calculate a 0-100 score based on:++| Factor | Weight | Scoring |+|--------|--------|---------|+| Referring domain count | 20% | Scale based on industry benchmarks |+| Domain quality distribution | 20% | % from authority domains (DR 40+) |+| Anchor text naturalness | 15% | Penalty for over-optimization |+| Toxic link ratio | 20% | <2% = full score, >10% = 0 |+| Link velocity trend | 10% | Growing = full, declining = partial |+| Follow/nofollow ratio | 5% | >60% follow = full score |+| Geographic relevance | 10% | % from target market countries |++## Output Format++### Backlink Health Score: XX/100++| Section | Status | Score |+|---------|--------|-------|+| Profile Overview | pass/warn/fail | XX/100 |+| Anchor Distribution | pass/warn/fail | XX/100 |+| Referring Domain Quality | pass/warn/fail | XX/100 |+| Toxic Links | pass/warn/fail | XX/100 |+| Top Pages | info | N/A |+| Link Velocity | pass/warn/fail | XX/100 |++### Critical Issues (fix immediately)+### High Priority (fix within 1 month)+### Medium Priority (ongoing improvement)+### Link Building Opportunities (top 10)++## Error Handling++| Error | Cause | Resolution |+|-------|-------|-----------|+| DataForSEO tools unavailable | Extension not installed | Run `./extensions/dataforseo/install.sh` |+| No backlink data returned | Domain too new or very small | Note: small sites may have <10 backlinks |+| API credits insufficient | DataForSEO balance low | Check balance at app.dataforseo.com |++**Graceful fallback:** If DataForSEO is unavailable:+1. Inform user that backlink analysis requires the DataForSEO extension+2. Offer to check robots.txt and sitemap for basic link signals instead+3. Suggest manual tools: Ahrefs Webmaster Tools (free), Google Search Console Links report++## Reference Documentation++Load on demand (do NOT load at startup):+- `references/backlink-quality.md` -- Detailed toxic link patterns and scoring methodologydiff --git a/skills/seo/SKILL.md b/skills/seo/SKILL.mdindex c2c2df1..71b0b33 100644--- a/skills/seo/SKILL.md+++ b/skills/seo/SKILL.md@@ -51,6 +51,8 @@ e-commerce, publishers, agencies). Orchestrates 15 specialized sub-skills and 10| `/seo maps [command] [args]` | Maps intelligence (geo-grid, GBP audit, reviews, competitors) || `/seo hreflang [url]` | Hreflang/i18n SEO audit and generation || `/seo google [command] [url]` | Google SEO APIs (GSC, PageSpeed, CrUX, Indexing, GA4) |+| `/seo backlinks <url>` | Backlink profile analysis (requires DataForSEO extension) |+| `/seo firecrawl [command] <url>` | Full-site crawling and site mapping (extension) || `/seo dataforseo [command]` | Live SEO data via DataForSEO (extension) || `/seo image-gen [use-case] <description>` | AI image generation for SEO assets (extension) |@@ -62,6 +64,7 @@ When the user invokes `/seo audit`, delegate to subagents in parallel:3. If Google API credentials detected (`python scripts/google_auth.py --check`), also spawn seo-google agent4. If local business detected, also spawn seo-local agent5. If local business detected AND DataForSEO MCP available, also spawn seo-maps agent+6. If Firecrawl MCP available, use `firecrawl_map` to discover all site URLs before analysis6. Collect results and generate unified report with SEO Health Score (0-100)7. Create prioritized action plan (Critical -> High -> Medium -> Low)8. **Offer PDF report**: "Generate a professional PDF report? Use `/seo google report full`"@@ -141,8 +144,10 @@ This skill orchestrates 15 specialized sub-skills (+ 2 extensions):13. **seo-local** -- Local SEO (GBP, NAP, citations, reviews, local schema, multi-location)14. **seo-maps** -- Maps intelligence (geo-grid, GBP audit, reviews, competitor radius)15. **seo-google** -- Google SEO APIs (GSC, PageSpeed, CrUX, Indexing API, GA4)-16. **seo-dataforseo** -- Live SEO data via DataForSEO MCP (extension)-17. **seo-image-gen** -- AI image generation for SEO assets via Gemini (extension)+16. **seo-backlinks** -- Backlink profile analysis (requires DataForSEO extension)+17. **seo-firecrawl** -- Full-site crawling and site mapping via Firecrawl MCP (extension)+18. **seo-dataforseo** -- Live SEO data via DataForSEO MCP (extension)+19. **seo-image-gen** -- AI image generation for SEO assets via Gemini (extension)## Subagents@@ -159,6 +164,7 @@ For parallel analysis during audits:- `seo-google` -- CWV field data, URL indexation status, organic traffic trends (conditional: spawned when Google API credentials detected)- `seo-dataforseo` -- Live SERP, keyword, backlink, local SEO data (extension, optional)- `seo-image-gen` -- SEO image audit and generation plan (extension, optional)+- `seo-firecrawl` -- Full-site crawl and site mapping (extension, optional; used by audit for URL discovery)## Error Handlingdiff --git a/skills/seo/references/backlink-quality.md b/skills/seo/references/backlink-quality.mdnew file mode 100644index 0000000..d5fdb07--- /dev/null+++ b/skills/seo/references/backlink-quality.md@@ -0,0 +1,83 @@+# Backlink Quality Scoring Methodology++## Toxic Link Indicators (30 Patterns)++### Definite Spam (auto-flag)+1. Link from domain with 10,000+ outbound links per page+2. Link from domain with no indexed pages in Google+3. Link from domain registered <30 days ago with 100+ outbound links+4. Exact-match anchor text from 5+ unrelated domains+5. Links from doorway pages (thin content, keyword-stuffed)+6. Links from hacked sites (pharma/casino injections)+7. Links from known link networks (check against known PBN lists)+8. Footer/sidebar site-wide links from unrelated domains+9. Links from auto-generated content (spun articles)+10. Links from domains with manual Google penalties++### Likely Spam (manual review)+11. Links from domains with >90% outbound link ratio+12. Foreign-language domains linking to English content (and vice versa)+13. Links from expired/auctioned domains repurposed for link building+14. Links from pages with >50 outbound links+15. Links from sites with no real traffic (parked domains)+16. Reciprocal link patterns across 10+ domains+17. Links from Web 2.0 properties with thin content+18. Links from article directories (EzineArticles, ArticleBase)+19. Links from low-quality guest post networks+20. Links from unrelated niches (e.g., pet site linking to SaaS)++### Potentially Problematic (monitor)+21. Links from social bookmarking sites at scale+22. Links from forum profiles (not discussions)+23. Links from press release syndication networks+24. Links from coupon/deal aggregators+25. Links from generic directories (not industry-specific)+26. Links with hidden/invisible anchor text+27. Links from pages with cloaked content+28. Links from sites with thin affiliate content+29. Links from comment sections without editorial context+30. Links from nofollow-only domains (limited SEO value)++## Anchor Text Ratio Benchmarks by Industry++| Industry | Branded | URL | Generic | Exact Match | Partial Match |+|----------|---------|-----|---------|-------------|---------------|+| SaaS | 40-55% | 15-20% | 10-15% | 3-8% | 10-15% |+| E-commerce | 35-45% | 15-25% | 10-15% | 5-10% | 10-20% |+| Local Service | 45-60% | 10-15% | 15-20% | 5-10% | 5-10% |+| Publisher/Blog | 30-40% | 20-30% | 10-15% | 3-8% | 10-20% |+| Agency | 40-50% | 15-20% | 10-15% | 5-10% | 10-15% |++## Link Velocity Red Flags++| Pattern | Signal | Action |+|---------|--------|--------|+| 10x normal new links in 1 week | Possible negative SEO | Investigate source, prepare disavow |+| 50%+ links lost in 1 month | Penalty or site issues | Check GSC for manual actions |+| Zero new links for 3+ months | Content not attracting links | Review content strategy |+| All new links from same TLD | Coordinated link building | Diversify sources |+| Spike from single country | Link network activity | Review geographic sources |++## Disavow Recommendations++**When to disavow:**+- Domain has received a manual penalty from Google+- Clear evidence of negative SEO attack+- Toxic link ratio exceeds 10% of total profile+- Specific domains identified as PBN or link farms++**When NOT to disavow:**+- Low-quality links that Google likely ignores anyway+- Nofollow links (already devalued by Google)+- Links from legitimate but low-authority sites+- Small number of spam links (<2% of profile)++**Disavow file format:**+```+# Toxic domains identified by Claude SEO backlink analysis+# Date: YYYY-MM-DD+# Total domains disavowed: X+domain:spamsite1.com+domain:linkfarm2.net+domain:pbn-network3.xyz+```