# SEO Human Guide ## What This Is For Routes SEO tasks to the right specialist workflow for audits, local SEO, schema, sitemaps, images, and search optimization work. It gives the agent a clearer input/output frame for search and SEO workflows: what context to ask for, what decisions to make, and what usable artifact to return. Use this as a human-readable version of the SEO agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions. ## When To Use This - Use this when you need a repeatable process for SEO. - Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt. - Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact. ## When Not To Use This - Do not use this when you only need a quick factual answer. - Do not use this when the work depends on private data you cannot share with the assistant. - Do not use this as a replacement for legal, compliance, financial, or medical review. ## What You Need Before Starting - The goal or business outcome you want. - The audience, customer segment, or market context. - Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance. - Constraints such as tone, length, channel, deadline, region, or approval requirements. - A clear definition of what a good final answer should look like. ## Step-By-Step Workflow 1. State the job clearly: "Use the SEO guide to help me with..." 2. Add context: audience, goal, offer, channel, source material, and constraints. 3. Ask the assistant to identify missing inputs before producing the final output. 4. Have the assistant follow the skill-specific guidance below. 5. Review the result against the final checklist and ask for revisions where needed. ## Skill-Specific Guidance - Detect business type (SaaS, local, ecommerce, publisher, agency, other) - Spawn subagents: seo-technical, seo-content, seo-schema, seo-sitemap, seo-performance, seo-visual, seo-geo - If Google API credentials detected (`python3 scripts/google_auth.py --check`), also spawn seo-google agent - If local business detected, also spawn seo-local agent - If local business detected AND DataForSEO MCP available, also spawn seo-maps agent - If backlink APIs detected (`python3 scripts/backlinks_auth.py --check`), also spawn seo-backlinks agent - If Firecrawl MCP available, use `firecrawl_map` to discover all site URLs before analysis - If content strategy signals detected (blog, pillar pages, topic clusters), also spawn seo-cluster agent - If e-commerce detected, also spawn seo-ecommerce agent - If drift baseline exists for this URL (`python3 scripts/drift_history.py `), also spawn seo-drift agent - Always include seo-sxo in full audits (search experience applies to all sites) - Collect results and generate unified report with SEO Health Score (0-100) ## Decision Points And Nuance The original skill emphasizes: Quick Reference, Orchestration Logic, Synthesis Methodology, Industry Detection, Quality Gates, Community Footer, When to show, When to skip, Reference Files, Scoring Methodology. Use these questions to steer the work: - What is the intended audience or buyer? - What source material must be preserved? - What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion? - What examples represent the desired quality bar? - What should the assistant avoid? ## Common Mistakes - WARNING at 30+ location pages (enforce 60%+ unique content) - Never recommend HowTo schema (deprecated Sept 2023) - All Core Web Vitals references use INP, never FID - Do NOT show the footer after: - Load these on-demand as needed (do NOT load all at startup): - **Critical**: Blocks indexing or causes penalties (immediate fix required) - | URL unreachable | Report the error and suggest the user verify the URL. Do not attempt to guess site content. | - Trustworthiness is the most important factor. It is assessed based on the ## Copy-And-Paste Prompt ```text Use the SEO human guide. My goal: [Describe the business outcome] Audience: [Describe who this is for] Context and source material: [Paste notes, examples, links, or existing copy] Constraints: [Tone, length, channel, timeline, must-include items, must-avoid items] Before producing the final output, ask me for any missing information that would materially improve the result. ``` ## Final Checklist - [ ] The output matches the original goal. - [ ] The audience and context are reflected in the answer. - [ ] Important constraints and source material were preserved. - [ ] The assistant made the relevant decisions explicit. - [ ] The final artifact is ready to use, review, or hand to the next person. ## Source This guide was generated from the agricidaniel/claude-seo skill entry for `seo`. ## Source Skill Notes These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic. # SEO: Universal SEO Analysis Skill **Invocation:** `/seo $1 $2` where `$1` is the command and `$2` is the URL or argument. **Scripts:** Located at the plugin root `scripts/` directory. 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 | Command | What it does | |---------|-------------| | `/seo audit ` | Full website audit with parallel subagent delegation | | `/seo page ` | Deep single-page analysis | | `/seo sitemap ` | Analyze or generate XML sitemaps | | `/seo schema ` | Detect, validate, and generate Schema.org markup | | `/seo images ` | Image SEO: on-page audit, SERP analysis, file optimization | | `/seo technical ` | Technical SEO audit (9 categories) | | `/seo content ` | E-E-A-T and content quality analysis | | `/seo content-brief ` | Generate detailed SEO content brief with target keywords, outline, internal links | | `/seo geo ` | AI Overviews / Generative Engine Optimization | | `/seo plan ` | Strategic SEO planning | | `/seo programmatic [url\|plan]` | Programmatic SEO analysis and planning | | `/seo competitor-pages [url\|generate]` | Competitor comparison page generation | | `/seo local ` | 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 ` | Backlink profile analysis (free: Moz, Bing, CC; premium: DataForSEO) | | `/seo cluster ` | SERP-based semantic clustering and content architecture | | `/seo sxo ` | Search Experience Optimization: page-type analysis, user stories, personas | | `/seo drift baseline ` | Capture SEO baseline for change monitoring | | `/seo drift compare ` | Compare current state to stored baseline | | `/seo drift history ` | Show drift history over time | | `/seo ecommerce ` | E-commerce SEO: product schema, marketplace intelligence | | `/seo firecrawl [command] ` | Full-site crawling and site mapping (extension) | | `/seo dataforseo [command]` | Live SEO data via DataForSEO (extension) | | `/seo image-gen [use-case] ` | 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 | ## 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 (`python3 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 backlink APIs detected (`python3 scripts/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 (`python3 scripts/drift_history.py `), 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 `scripts/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`.