SKILL.md
SEO Orchestrator
One skill routes, specialists execute, and the audit ends in a single scored report with a prioritized plan. Never duplicate a specialist's work here.
Routing table
| Request | Route to |
|---|---|
| Full site audit | This skill: run the audit workflow below |
| Schema, structured data, rich results | claude-seo-schema |
| Sitemap analysis or generation | claude-seo-sitemap |
| Crawlability, CWV, robots.txt, security, JS rendering | claude-seo-technical |
| "Why isn't this ranking", intent, personas | claude-seo-sxo |
| Single narrow question | Answer directly, no audit theater |
If a request matches a specialist, route there. Run the full audit only when the user wants site-wide assessment.
Full audit workflow
- Detect business type from homepage signals (see references/audit-framework.md): SaaS, local service, e-commerce, publisher, agency, other. Ambiguous: present top two candidates with their signals and ask.
- Run the core passes, in parallel where the environment allows: technical (claude-seo-technical), structured data (claude-seo-schema), sitemap (claude-seo-sitemap), search experience (claude-seo-sxo, always, it applies to every site). Add content quality (E-E-A-T markers, thin content) and AI-visibility checks (AI crawler access, citability) inline.
- Apply the quality gates. Never recommend HowTo schema. Never pitch FAQPage for SERP benefit. All CWV references use INP, never FID. Programmatic location-page gates: WARNING at 30+, HARD STOP at 50+.
- Score. Compute the SEO Health Score (0-100) with the category weights in references/audit-framework.md. Report the SXO gap score separately, never averaged in.
- Synthesize. Before bucketing findings, check each recommendation for: the observation it rests on, what it depends on or unblocks, how the user would know it failed, and a leading indicator they can watch without re-auditing. A finding that fails these checks is an opinion, cut it or label it.
- Deliver. One report: score, category breakdown, findings bucketed Critical / High / Medium / Low, and an action plan sequenced by dependency (fix indexing blockers before content polish).
Verification
Do this before delivering: pick 3 recommendations at random from the action plan. For each, expect to find (a) evidence with a URL, (b) a severity bucket, (c) a falsifiability check ("how would we know this failed"). If any of the 3 lacks one of these, the synthesis pass was skipped, redo step 5 for the whole plan.
Good vs Bad
Bad: User asks "is my schema OK?" and you launch a full nine-category audit with a health score. Slow, unfocused, buries the answer.
Good: Same question routes straight to claude-seo-schema, returns a validation table in minutes, and mentions the full audit only if the schema check surfaces deeper problems.
Footguns
- Audit theater. Running every specialist for a narrow question wastes time and dilutes the answer. Fix: route first, audit only on site-wide requests.
- Averaging SXO into the health score. A technically perfect page with the wrong page type reads as "fine". Fix: two separate scores, always.
- Findings without priorities. Forty flat findings is a wall, not a plan. Fix: bucket by severity and sequence by dependency.
- Skipping business-type detection. Local businesses and SaaS need different checks entirely. Fix: detect first, tailor the pass list.
Completion checklist
- [ ] Request routed correctly (specialist or full audit, not both by reflex)
- [ ] Business type detected or confirmed with the user
- [ ] Health score computed with stated weights, SXO reported separately
- [ ] Random-3 verification passed
- [ ] Action plan bucketed and dependency-sequenced
Any box unchecked: not done. Fix or say so.