seo-audit

---
name: seo-audit
description: Orchestrates a multi-specialist SEO audit — detects business type, dispatches the available specialist skills, and aggregates one weighted health score with a prioritized, deduped fix list. Crawls up to ~500 pages when seo-firecrawl is connected; otherwise audits the key URLs you provide and says so. Trigger when the user says "seo audit", "full site audit", "comprehensive seo review", "analyze my site for seo", "website health check", or "audit my site for seo".
license: MIT
---

# seo-audit

**Family:** seo
**Status:** Stable

## Purpose

The orchestrator and public face of the SEO family. Runs the available specialist
skills against your target, then aggregates their findings into one weighted health
score with a prioritized fix list — so the user gets a single answer, not eight
disconnected reports.

Scope note (honest): it audits the **URLs you provide** out of the box. Full-site
crawling (up to ~500 pages, business-type auto-detect at scale) activates when the
`seo-firecrawl` skill is installed; without it, point it at the key URLs.

## Triggers

- "seo audit" / "full site audit" / "comprehensive seo review"
- "analyze my site for SEO" / "website health check"
- "audit [domain]"

## Inputs

- A domain, a URL, or a small list of key URLs
- Optional: business-type override; specialist include/exclude

## Steps

1. **Scope.** Take the URL(s). If `seo-firecrawl` is available, crawl to discover
   pages; otherwise audit the provided URLs and say so.
2. **Profile.** Infer business type (SaaS / e-commerce / local / publisher /
   agency) from the content to decide which conditional specialists apply.
3. **Dispatch the specialist agents in parallel** — real Agent-tool sub-agents, each
   a dispatched leaf under `agents/` (one-directional, no back-edges). The full roster
   and the dispatch conditions are in `references/seo-audit/dispatch-matrix.md`. Always
   fan out the five always-on agents:
   - `seo-page` — per-URL on-page review
   - `seo-technical` — technical dimensions (`tech_audit.py`)
   - `seo-schema` — structured-data validation
   - `seo-sitemap` — sitemap structure + gates
   - `seo-image-audit` — image SEO
   Then add the conditional agents the profile and connected tooling call for:
   `seo-content` (content depth / E-E-A-T) and `seo-geo` (AI-citability) by default,
   plus `seo-local-unified` for a local business or `seo-ecommerce` for a store; when
   their tools are connected, also `seo-google` (real CWV / rankings) and
   `seo-backlinks`. Each agent obeys the plugin's tier cascade and returns its
   machine-parseable `## Output contract` block for deterministic fan-in. Record which
   specialists ran and which were skipped (and why) rather than implying coverage you
   didn't run.
4. **Aggregate + score.** Collect each agent's Output-contract score and feed the
   per-specialist map to `scripts/workflow/audit_aggregate.py`, which computes one
   weighted health score (0–100) **re-normalized over the specialists that actually
   ran** — a skipped specialist is excluded from the denominator, never zeroed. The
   weight table (anchors `seo-technical` and `seo-page` at 20; `seo-content` 15; the
   mid band at 10; `seo-geo` 5) and the grade bands are in
   `references/seo-audit/scoring-weights.md`. Report the weighting used.

   ```
   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflow/audit_aggregate.py" --file scores.json --human
   ```
5. **Prioritize.** Merge findings into one list: Critical → High → Medium → Low,
   deduped, each with the owning specialist and a specific fix.
6. **Render** the health score, the prioritized fix list, and per-specialist
   appendices. State explicitly which specialists ran and which were skipped.

## Outputs

- Weighted health score (0–100) with the weighting shown
- One prioritized, deduped fix list (Critical/High/Medium/Low)
- Per-specialist detail appendices + an explicit "covered / not covered" list

## Dependencies

- Core specialists (always): `seo-page`, `seo-technical`, `seo-schema`, `seo-sitemap`,
  `seo-image-audit` — each dispatched as its `agents/<name>.md` leaf
- Conditional specialists (by business type / connected tooling): `seo-content`,
  `seo-geo`, `seo-local-unified`, `seo-ecommerce`, `seo-google`, `seo-backlinks`
- `references/seo-audit/dispatch-matrix.md` (required) — the always/conditional roster
  + dispatch conditions the Steps fan out over
- `references/seo-audit/scoring-weights.md` (required) — the health-score weight table
  + re-normalization + grade bands
- `scripts/workflow/audit_aggregate.py` (required) — re-normalized health-score fan-in
- `scripts/seo/business_type.py` (required) — business-type classification for
  conditional dispatch
- Optional: `seo-firecrawl` (full-site crawl)

## Notes

Most SEO requests should land here first; it routes to specialists. It dispatches
real Agent-tool sub-agents in parallel (`agents/`), one per specialist leaf, and never
claims coverage it didn't run — the "covered / not covered" list plus the
re-normalized denominator keep the health score honest. Adding a new specialist agent
auto-joins this socket (see `references/seo-audit/dispatch-matrix.md`).