SEO

SEO: Universal SEO Analysis Skill

Invocation: /seo $1 $2 where $1 is the command and $2 is the URL or argument.

Runtime: Run bundled Python tools through "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run <script.py>. That is the single canonical form used by every skill and agent. Claude Code expands ${CLAUDE_PLUGIN_ROOT} to the installed plugin directory, so the launcher is found without any PATH entry; the repository ships no top-level bin/ directory because hosted marketplaces reject one. Repository users run ./scripts/claude-seo; manual installers rewrite the canonical form to "$HOME/.claude/skills/seo/scripts/claude-seo". Never invoke bundled scripts with a bare Python interpreter.

Comprehensive SEO analysis across all industries (SaaS, local services, e-commerce, publishers, agencies). Orchestrates 24 sub-skills (21 core + 1 framework integration + 2 extension mirrors) and 18 sub-agents. A separate optional Firecrawl extension is also installable (see "Optional Extensions" below).

Quick Reference

Runtime Setup

Run setup only when the user explicitly invokes /seo setup or explicitly asks to repair dependencies. Execute "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" setup, report core and Chromium status separately, and do not fall back to global or user package installation. For diagnosis, execute "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" doctor --json; its output intentionally omits absolute paths and environment values. If any "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run command reports that setup is required, suggest /seo setup and do not improvise a pip install.

Orchestration Logic

When the user invokes /seo audit, delegate to subagents in parallel:

1. Detect business type (SaaS, local, ecommerce, publisher, agency, other)
2. Spawn subagents: seo-technical, seo-content, seo-schema, seo-sitemap, seo-performance, seo-visual, seo-geo
3. If Google API credentials detected ("${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run 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 backlink APIs detected ("${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run backlinks_auth.py --check), also spawn seo-backlinks agent
7. If Firecrawl MCP available, use firecrawl_map to discover all site URLs before analysis
8. If content strategy signals detected (blog, pillar pages, topic clusters), also spawn seo-cluster agent
9. If e-commerce detected, also spawn seo-ecommerce agent
10. If drift baseline exists for this URL ("${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run drift_history.py <url>), also spawn seo-drift agent
11. Always include seo-sxo in full audits (search experience applies to all sites)
12. Collect results and generate unified report with SEO Health Score (0-100)
13. Synthesize via the 10-principle framework (see "Synthesis Methodology" below), walk PERCEIVE → ANALYZE → VALIDATE → ACT before bucketing findings into Critical / High / Medium / Low
14. Create prioritized action plan with dependency sequencing + falsifiability per recommendation
15. Offer PDF report: "Generate a professional PDF report? Use /seo google report full"

For individual commands, load the relevant sub-skill directly. After any analysis command completes, offer to generate a PDF report via "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run google_report.py.

Synthesis Methodology

Audits are not just findings, they are findings synthesized into a coherent strategy. claude-seo uses a 10-principle thinking framework grouped into four phases: PERCEIVE (observe-external · observe-internal · listen), ANALYZE (think · connect-lateral · connect-system), VALIDATE (feel · accept), ACT (create · grow).

Full audits (/seo audit, /seo page) walk every phase before emitting the action plan. Narrower commands (/seo schema, /seo images, etc.) pass at least THINK + ACCEPT before emitting (sound first principle, surfaced falsifiability). The Critical / High / Medium / Low priority buckets are the output of validation, not a substitute for it.

Full methodology + per-principle SEO mapping: references/thinking-framework.md.

Each emitted recommendation should carry:

• The first-principle observation it rests on (THINK)
• The dependency on / unblock relationship to other recommendations (CONNECT-system)
• An explicit "how would we know this failed?" check (ACCEPT)
• A leading indicator the user can monitor without re-running the audit (GROW)

Industry Detection

Detect business type from homepage signals:

• SaaS: pricing page, /features, /integrations, /docs, "free trial", "sign up"
• Local Service: phone number, address, service area, "serving [city]", Google Maps embed --> auto-suggest /seo local for deeper analysis
• E-commerce: /products, /collections, /cart, "add to cart", product schema
• Publisher: /blog, /articles, /topics, article schema, author pages, publication dates
• Agency: /case-studies, /portfolio, /industries, "our work", client logos

Quality Gates

Read references/quality-gates.md for thin content thresholds per page type. Hard rules:

• WARNING at 30+ location pages (enforce 60%+ unique content)
• HARD STOP at 50+ location pages (require user justification)
• Never recommend HowTo schema (deprecated Sept 2023)