Skip to content

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.json
index 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.md
index 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
### Fixed
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 Principles
1. **Progressive Disclosure**: Metadata always loaded, instructions on activation, resources on demand
2. **Industry Detection**: Auto-detect SaaS, e-commerce, local, publisher, agency
3. **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 generation
diff --git a/README.md b/README.md
index 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
## Documentation
diff --git a/extensions/firecrawl/README.md b/extensions/firecrawl/README.md
new file mode 100644
index 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.md
new file mode 100644
index 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.ps1
new file mode 100644
index 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.sh
new file mode 100644
index 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.md
new file mode 100644
index 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.ps1
new file mode 100644
index 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.sh
new file mode 100644
index 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.ps1
index 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 directories
New-Item -ItemType Directory -Force -Path $SkillDir | Out-Null
diff --git a/install.sh b/install.sh
index 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.txt
index eb32bec..f88cf0e 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -10,9 +10,10 @@ Pillow>=12.1.0,<13.0.0 # CVE-2025-48379 fix
urllib3>=2.6.3,<3.0.0 # CRITICAL: CVE-2026-21441 (CVSS 8.9), CVE-2025-66418
validators>=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 CVEs
weasyprint>=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 CVEs
diff --git a/scripts/google_report.py b/scripts/google_report.py
index 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.md
new file mode 100644
index 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 methodology
diff --git a/skills/seo/SKILL.md b/skills/seo/SKILL.md
index 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 agent
4. If local business detected, also spawn seo-local agent
5. 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 analysis
6. 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 Handling
diff --git a/skills/seo/references/backlink-quality.md b/skills/seo/references/backlink-quality.md
new file mode 100644
index 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
+```