seo

Files (19)

• LICENSE.txt
• SKILL.md
• backlink-quality.md · references/
• cwv-thresholds.md · references/
• eeat-framework.md · references/
• eeat-scoring-guide.md · references/
• free-backlink-sources.md · references/
• local-schema-multilocation.md · references/
• local-schema-types.md · references/
• local-search-behavior.md · references/
• local-seo-signals.md · references/
• maps-api-endpoints.md · references/
• maps-free-apis.md · references/
• maps-gbp-checklist.md · references/
• maps-geo-grid.md · references/
• quality-gates.md · references/
• schema-types.md · references/
• thinking-framework-validate-act.md · references/
• thinking-framework.md · references/

SKILL.md (first lines)

# 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 25 sub-skills (22 core + 1 framework
integration + 2 extension mirrors) and 19 sub-agents. A separate optional Firecrawl
extension is also installable (see "Optional Extensions" below).

## Quick Reference

| Command | What it does |
|---------|-------------|
| `/seo audit <url>` | Full website audit with parallel subagent delegation |
| `/seo page <url>` | Deep single-page analysis |
| `/seo sitemap <url or generate>` | Analyze or generate XML sitemaps |
| `/seo schema <url>` | Detect, validate, and generate Schema.org markup |
| `/seo images <url or optimize>` | Image SEO: on-page audit, SERP analysis, file optimization |
| `/seo technical <url>` | Technical SEO audit (9 categories) |
| `/seo content <url>` | E-E-A-T and content quality analysis |
| `/seo content-brief <topic or url>` | Generate detailed SEO content brief with target keywords, outline, internal links |
| `/seo geo <url>` | AI Overviews / Generative Engine Optimization |
| `/seo agentic [audit\|fix\|lighthouse\|refresh] <url>` | Agent readiness: Lighthouse Agentic Browsing X/N, accessibility tree, AI agent access, llms.txt, Markdown, WebMCP |
| `/seo plan <business-type>` | Strategic SEO planning |
| `/seo programmatic [url\|plan]` | Programmatic SEO analysis and planning |
| `/seo competitor-pages [url\|generate]` | Competitor comparison page generation |
| `/seo local <url>` | Local SEO analysis (GBP, citations, reviews, map pack) |
| `/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 (free: Moz, Bing, CC; premium: DataForSEO) |
| `/seo cluster <seed-keyword>` | SERP-based semantic clustering and content architecture |
| `/seo sxo <url>` | Search Experience Optimization: page-type analysis, user stories, personas |
| `/seo drift baseline <url>` | Capture SEO baseline for change monitoring |
| `/seo drift compare <url>` | Compare current state to stored baseline |
| `/seo drift history <url>` | Show drift history over time |
| `/seo ecommerce <url>` | E-commerce SEO: product schema, marketplace intelligence |
| `/seo matomo [command] [args]` | Matomo Reporting API: GA4 alternative or supplement (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) |
| `/seo flow [stage] [url\|topic]` | FLOW framework: evidence-led prompts for Find, Leverage, Optimize, Win, or Local stages |
| `/seo setup` | Explicitly create or refresh the isolated Python runtime and Chromium |
| `/seo doctor` | Check runtime readiness without changing the system |

## 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, seo-agentic
3. If Google API credentials detected (`"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run google_auth.py --check`), also spawn seo-google agent
4. If Matomo credentials detected (`"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run matomo_auth.py --check`), also spawn seo-matomo agent (alternative or complement to seo-google's GA4 reports)
5. If local business detected, also spawn seo-local agent
6. If local business detected AND DataForSEO MCP available, also spawn seo-maps agent
7. Spawn seo-backlinks agent for Common Crawl domain-level metrics, adding Moz and Bing data when their credentials are detected (`"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run backlinks_auth.py --check`)
8. If Firecrawl MCP available, use `firecrawl_map` to discover all site URLs before analysis
9. If content strategy signals detected (blog, pillar pages, topic clusters), also spawn seo-cluster agent
10. If e-commerce detected, also spawn seo-ecommerce agent
11. If drift baseline exists for this URL (`"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run drift_history.py <url>`), also spawn seo-drift agent
12. Always include seo-sxo in full audits (search experience applies to all sites)
13. Collect results and generate unified report with SEO Health Score (0-100)
14. **Synthesize via the 10-principle framework** (see "Synthesis Methodology" below), walk PERCEIVE → ANALYZE → VALIDATE → ACT before bucketing findings into Critical / High / Medium / Low
15. Create prioritized action plan with dependency sequencing + falsifiability per recommendation
16. **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`.

**Google update history questions** (core, spam, policy, product changes; "is the
spam update finished?"): answer from the bundled primary-source ledger, not from
memory or other copies on disk. Run
`"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run seo_updates.py --kind spam --json`
(or `--since <yyyy-mm>`; add `--unverified` for third-party claims that are not
confirmed). If the output reports the ledger as stale, check
status.search.google.com before stating that a rollout is complete.

## 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` (VALIDATE and ACT in `references/thinking-framework-validate-act.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)

From AgriciDaniel/claude-seo, MIT.

More from AgriciDaniel/claude-seo