name: seo-core description: > Shared SEO utilities and core references. Houses critical scripts (project manager, pre-scan, score aggregator) and SEO guidelines (E-E-A-T, CWV, schema standards, quality gates) shared across all specialist skills. Loaded as a base utility. Related: seo-audit (technical), seo-writer (content), seo-geo (AI visibility) triggers: "seo kit manager, seo project core, seo settings database, seo kit base, seo health score, quality gates, eeat framework, core web vitals threshold, seo onboarding, seo checklist, seo lifecycle, search everywhere optimization"

SEO: Core Utilities & References Index

Provides shared utility scripts and core reference files for the entire SEO Kit. The active coordination of the lifecycle is handled by the seo-orchestrator agent and its associated workflows.

Why a Lifecycle Matters

Think of SEO like a medical process. You wouldn't prescribe medicine (Execute) before diagnosis (Audit), and you wouldn't diagnose without knowing the patient (Onboard). Each phase builds on the previous one because:

• Onboard first — Without brand identity and API access, audits produce generic advice
• Research before Audit — Keywords and audience data inform what to look for
• Audit before Strategy — Can't plan fixes without knowing what's broken
• Strategy before Execute — Prioritization prevents wasting effort on low-impact changes
• Monitor after Execute — The only way to prove SEO work actually helped

Skipping phases leads to: wrong priorities, wasted effort, hallucinated recommendations.

SEO Lifecycle (5 Phases + Deep Dives)

📋 ONBOARD → 🔎 RESEARCH → 🔍 AUDIT → 🧠 STRATEGY → ⚡ EXECUTE → 📈 MONITOR → (loop)

Master Command: /seo-run

The primary entry point. Reads project.json, determines current phase, and suggests the next action. Never auto-executes — always waits for user approval.

Direct Skill Access

Users can always call any skill directly by name without the lifecycle:

• "Run seo-entity for example.com" → reads seo-entity/SKILL.md directly
• Direct calls do NOT affect the project phase state.

Phase Details

Phase 1: Onboard (/seo-onboard)

WHY: Establishes baseline — without knowing the brand, APIs, and industry, every later phase produces generic advice.

Research (/seo-research)

WHY: "What do users actually search for?" Without this data, audit findings can't be prioritized by business impact.

Phase 2: Audit (/seo-audit)

WHY: The diagnostic. Identifies what's broken, what's missing, and what's already working. Everything downstream depends on accurate diagnosis.

Phase 3: Strategy (/seo-strategy)

WHY: Turns raw audit findings into a prioritized roadmap. Without strategy, teams fix easy things instead of impactful things.

Phase 4: Execute (/seo-execute)

WHY: Generates actual code and content. This is where analysis becomes action — meta tags, schema JSON-LD, redirect maps, content briefs.

Phase 5: Monitor (/seo-monitor)

WHY: Proves ROI and catches regressions. Without monitoring, you can't tell if changes helped or if competitors overtook you.

Utility: /seo-page

Special: /seo-local-suite

Quality Gates (CRITICAL — read every time)

• Never recommend HowTo schema (deprecated Sept 2023)
• FAQ schema for Google rich results: only government and healthcare sites (Aug 2023); existing FAQPage on commercial sites → flag as Info (not Critical), noting AI/LLM citation benefit; adding new FAQPage → not recommended for Google
• All Core Web Vitals references use INP, never FID
• WARNING at 30+ location pages (enforce 60%+ unique content)
• HARD STOP at 50+ location pages (require user justification)
• Read references/quality-gates.md for thin content thresholds per page type

Orchestration Logic

Auto-Routing (Natural Language)

When user sends a natural language request (no slash command), the rules/seo-auto-routing.md rule (always_on) automatically:

1. Detect URLs/domains in the request
2. Match SEO intent keywords (Vietnamese + English)
3. Load project state if domain project exists
4. Route to the correct workflow or individual skill
5. Announce: 🔍 SEO Auto-routing: [intent] → [workflow/skill]

Routing Examples

Explicit Command: /seo-run

When /seo-run is invoked:

1. Parse domain from URL
2. Load/create project.json per .agents/rules/seo-domain-project.md
3. Read phase field from project.json
4. Display status dashboard (phase, score, last run, history)
5. Suggest next phase workflow
6. Wait for user approval before executing

Direct Workflow/Skill Invocation

When a phase workflow is invoked directly (e.g., /seo-audit):

1. Init/load domain project
2. Activate the listed specialist skills
3. Execute analysis — comply with .agents/rules/seo-core.md
4. Update project.json with new phase and results
5. Suggest next step

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-suite
• 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

Utility Scripts

Scoring Methodology

SEO Health Score (0-100)

Weighted aggregate of all categories:

Priority Levels

• Critical: Blocks indexing or causes penalties (immediate fix required)
• High: Significantly impacts rankings (fix within 1 week)
• Medium: Optimization opportunity (fix within 1 month)
• Low: Nice to have (backlog)

Error Handling

Reference Files

Load on-demand as needed (do NOT load all at startup):

• references/cwv-thresholds.md: Core Web Vitals thresholds and measurement
• references/schema-types.md: Supported schema types with deprecation status
• references/eeat-framework.md: E-E-A-T evaluation criteria (Sept 2025 QRG)
• references/quality-gates.md: Content length minimums, uniqueness thresholds
• references/local-seo-signals.md: Local ranking factors, review benchmarks
• references/local-schema-types.md: LocalBusiness subtypes, industry-specific schema
• references/skill-index.md: Full list of all 43 sub-skills with descriptions
• references/architecture.md: File tree structure and development rules

Maps-specific (loaded by seo-maps, not at startup):

• references/maps-geo-grid.md, references/maps-gbp-checklist.md, references/maps-api-endpoints.md, references/maps-free-apis.md

Key Principles

1. Lifecycle-Driven: 5-phase flow because each phase depends on the previous
2. Suggest + Approve: AI never auto-executes — always waits for approval
3. Progressive Disclosure: Metadata always loaded, instructions on activation, references on demand
4. Industry Detection: Auto-detect SaaS, e-commerce, local, publisher, agency
5. Direct Access: Users can call skills directly, bypassing lifecycle
6. Extension System: DataForSEO, Banana, Ahrefs, Semrush (v2+)
7. Domain Workspaces: All outputs in .seo/ folders
8. Namespaced Rules: All .agents/rules/ use seo- prefix to avoid conflicts
9. No agent.md: SEO Kit does NOT install its own agent.md to avoid conflicts with base kits