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.

Add CLAUDE.md, CONTRIBUTING.md, and uninstall.ps1

AgriciDanielda01ac0abda9
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8427477
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,82 @@
+# Claude SEO — Universal SEO Analysis Skill
+
+## Project Overview
+
+This repository contains **Claude SEO**, a Tier 4 Claude Code skill for comprehensive
+SEO analysis across all industries. It follows the Agent Skills open standard and the
+3-layer architecture (directive, orchestration, execution). 13 sub-skills, 6 parallel
+subagents, and an extensible reference system cover technical SEO, content quality,
+schema markup, image optimization, sitemap architecture, and AI search optimization.
+
+## Architecture
+
+```
+claude-seo/
+ CLAUDE.md # Project instructions (this file)
+ .claude-plugin/plugin.json # Plugin manifest (v1.3.0)
+ seo/ # Main orchestrator skill
+ SKILL.md # Entry point, routing table, core rules
+ references/ # On-demand knowledge files
+ scripts/ # Python execution scripts
+ hooks/ # Quality gate hooks
+ skills/ # 12 specialized sub-skills
+ seo-audit/SKILL.md # Full site audit with parallel agents
+ seo-page/SKILL.md # Deep single-page analysis
+ seo-technical/SKILL.md # Technical SEO (8 categories)
+ seo-content/SKILL.md # E-E-A-T and content quality
+ seo-schema/SKILL.md # Schema.org markup detection/generation
+ seo-sitemap/SKILL.md # XML sitemap analysis/generation
+ seo-images/SKILL.md # Image optimization analysis
+ seo-geo/SKILL.md # AI search / GEO optimization
+ seo-plan/SKILL.md # Strategic SEO planning
+ seo-programmatic/SKILL.md # Programmatic SEO at scale
+ seo-competitor-pages/SKILL.md # Competitor comparison pages
+ seo-hreflang/SKILL.md # International SEO / hreflang
+ agents/ # 6 parallel subagents
+ seo-technical.md # Crawlability, indexability, security
+ seo-content.md # E-E-A-T, readability, thin content
+ seo-schema.md # Structured data validation
+ seo-sitemap.md # Sitemap quality gates
+ seo-performance.md # Core Web Vitals, page speed
+ seo-visual.md # Screenshots, mobile rendering
+ docs/ # Extended documentation
+ ARCHITECTURE.md # System design overview
+ COMMANDS.md # Full command reference
+ INSTALLATION.md # Install guide
+ MCP-INTEGRATION.md # DataForSEO MCP setup
+ TROUBLESHOOTING.md # Common issues
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/seo audit <url>` | Full site audit with 6 parallel subagents |
+| `/seo page <url>` | Deep single-page analysis |
+| `/seo technical <url>` | Technical SEO audit (8 categories) |
+| `/seo content <url>` | E-E-A-T and content quality analysis |
+| `/seo schema <url>` | Schema.org detection, validation, generation |
+| `/seo sitemap <url>` | XML sitemap analysis or generation |
+| `/seo images <url>` | Image optimization analysis |
+| `/seo geo <url>` | AI search / Generative Engine Optimization |
+| `/seo plan <type>` | Strategic SEO planning by industry |
+| `/seo programmatic` | Programmatic SEO analysis and planning |
+| `/seo competitor-pages` | Competitor comparison page generation |
+| `/seo hreflang <url>` | International SEO / hreflang audit |
+
+## Development Rules
+
+- Keep SKILL.md files under 500 lines / 5000 tokens
+- Reference files should be focused and under 200 lines
+- Scripts must have docstrings, CLI interface, and JSON output
+- Follow kebab-case naming for all skill directories
+- Agents invoked via Task tool with `context: fork`, never via Bash
+- Python dependencies install into `~/.claude/skills/seo/.venv/`
+- Test with `python -m pytest tests/` after changes (if applicable)
+
+## 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 6 subagents simultaneously
+4. **Extension System**: DataForSEO MCP integration for live data
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a6bb07f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,41 @@
+# Contributing to claude-seo
+
+Thanks for your interest in contributing! Here's how to get involved.
+
+## Reporting Bugs
+
+Open a [GitHub Issue](https://github.com/AgriciDaniel/claude-seo/issues) with:
+
+- Your OS and Python version
+- The full error output (copy from terminal)
+- The command or step that failed
+- The URL you were analyzing (if applicable)
+
+## Suggesting Features
+
+Use [GitHub Discussions](https://github.com/AgriciDaniel/claude-seo/discussions) for feature ideas and questions.
+
+## Pull Requests
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes
+4. Test with a sample URL before submitting
+5. Submit a PR with a clear description of what changed and why
+
+### Development Setup
+
+```bash
+git clone https://github.com/YOUR_USERNAME/claude-seo.git
+cd claude-seo
+bash install.sh
+```
+
+### Guidelines
+
+- All Python scripts should output JSON for Claude Code to parse
+- Shell scripts should use `set -euo pipefail` for safety
+- SKILL.md files must stay under 500 lines
+- Reference files should be focused and under 200 lines
+- Follow kebab-case naming for all directories and files
+- Keep dependencies minimal
diff --git a/uninstall.ps1 b/uninstall.ps1
new file mode 100644
index 0000000..7e73a18
--- /dev/null
+++ b/uninstall.ps1
@@ -0,0 +1,58 @@
+#!/usr/bin/env pwsh
+# claude-seo uninstaller for Windows
+# Cleanly removes all SEO skills, agents, and scripts
+
+$ErrorActionPreference = "Stop"
+
+function Write-Color($Color, $Text) {
+ Write-Host $Text -ForegroundColor $Color
+}
+
+function Main {
+ $SkillDir = Join-Path $env:USERPROFILE ".claude" "skills"
+ $AgentDir = Join-Path $env:USERPROFILE ".claude" "agents"
+
+ Write-Color Cyan "=== Uninstalling claude-seo ==="
+ Write-Host ""
+
+ # Remove main skill (includes venv, references, scripts, hooks)
+ $seoDir = Join-Path $SkillDir "seo"
+ if (Test-Path $seoDir) {
+ Remove-Item -Recurse -Force $seoDir
+ Write-Color Green " Removed: $seoDir"
+ }
+
+ # Remove sub-skills
+ $subSkills = @(
+ "seo-audit", "seo-competitor-pages", "seo-content", "seo-geo",
+ "seo-hreflang", "seo-images", "seo-page", "seo-plan",
+ "seo-programmatic", "seo-schema", "seo-sitemap", "seo-technical"
+ )
+ foreach ($skill in $subSkills) {
+ $skillPath = Join-Path $SkillDir $skill
+ if (Test-Path $skillPath) {
+ Remove-Item -Recurse -Force $skillPath
+ Write-Color Green " Removed: $skillPath"
+ }
+ }
+
+ # Remove agents
+ $agents = @(
+ "seo-technical", "seo-content", "seo-schema",
+ "seo-sitemap", "seo-performance", "seo-visual"
+ )
+ foreach ($agent in $agents) {
+ $agentPath = Join-Path $AgentDir "$agent.md"
+ if (Test-Path $agentPath) {
+ Remove-Item -Force $agentPath
+ Write-Color Green " Removed: $agentPath"
+ }
+ }
+
+ Write-Host ""
+ Write-Color Cyan "=== claude-seo uninstalled ==="
+ Write-Host ""
+ Write-Color Yellow "Restart Claude Code to complete removal."
+}
+
+Main