seo-audit

OpenSEO SEO Audit

Goal

Audit a domain and produce a one-page HTML report that anyone, including a complete SEO beginner, can read once and act on. The whole report exists to support ONE action the owner can take this week; everything else is supporting detail.

Use this when asked for an SEO audit or review of a domain, especially when the output is a shareable report for a non-expert. For expert-facing analysis of a competitor or market, use competitor-analysis or competitive-landscape instead.

Required inputs

• Domain to audit
• projectId (use list_projects; if no project matches the domain, create one with create_project)

Project context

The project-context tools are free and shared with the app and other agents.

1. Call get_project_context first and ground the report in it — what the business does decides which findings matter and what the one thing should be.
2. This skill needs business_overview. If it is empty, run a minimal inline setup: infer what the business does from the site and confirm it with the user in one question, write it back with update_project_context, then continue the audit. Never front-load the full interview; suggest seo-project-setup at the end for the rest.
3. Before spending credits, check the research log. If the same research ran within the last 30 days, reuse that result and say so instead of re-buying it.
4. On finish, write back what is durable — a corrected business_overview, the pages the report singles out via addKeyPages — and append a research log entry: { appendResearchLog: { summary: "Site audit: <domain>. Verdict: <conclusion>" } }.

Deliver as a report

Deliver through the seo-report skill, saving with skill: "seo-audit". If that skill is not available, say so and stop before writing HTML.

OpenSEO MCP tools

• whoami: confirm connection and remaining credits before spending anything. If OpenSEO is not connected, stop and ask the user to connect it.
• list_projects / create_project: resolve the projectId.
• run_site_audit: start the crawl (default page budget). Leave Lighthouse off (its default) — it adds several minutes and this report doesn't need it; pass runLighthouse: true only when the user asks for performance/Core Web Vitals depth. Then check get_audit_status (the crawl takes a minute or two — wait between checks rather than polling in a loop) and read get_audit_issues. Use get_audit_pages when per-page evidence helps.
• get_backlinks_overview: backlink and referring-domain picture; usually the deciding data for the "one thing".
• get_domain_overview: estimated organic traffic and organic keyword count. Skip when the site is clearly dead.
• research_keywords: keyword ideas with volume and difficulty, used to propose a starting focus area. One call with 1-3 seeds taken from what the site is actually about. Skip when the site is down.

Keep total spend modest: one audit, one backlinks overview, at most one domain overview, and at most one keyword-research call. Only the overview and keyword lookups spend credits.

Workflow

1. whoami, then resolve the projectId.
2. run_site_audit for the domain (Lighthouse stays off unless the user asked for performance depth). While it crawls, fetch get_backlinks_overview.
3. When the crawl finishes, read get_audit_issues (and get_domain_overview if the site is alive).
4. If the audit comes back broken or nearly empty (certificate errors, 5xx, one page crawled): investigate before writing. Check the certificate and redirect variants yourself, and search the web for the business. A dead domain often has a live successor site, which flips the whole recommendation to "redirect the old domain".
5. Verify every finding you plan to report against the live page HTML by fetching pages yourself. Report nothing you have not seen evidence for.
6. Decide the one thing. Derive it from the data, never from generic advice. Common patterns:
   • Clean site, no backlinks: outreach to guests, partners, or directories, with a ready-to-send message.
   • Dead domain, live successor site: permanent redirect via hosting support, with the exact sentence to send them.
   • Blocked or noindexed pages: remove the block. It must be doable this week by a non-technical person, with copy-paste-ready mechanics included.
7. When the site is healthy, propose a starting focus area: run one research_keywords call seeded from the site's actual topic, then pick one theme and 3 to 5 specific, low-difficulty keywords the site can realistically rank for, each with the page or post to make. This is a starting direction, not a keyword strategy; point the user at the keyword-research skill for the full workflow. Skip this step entirely when the site is down — the one thing is all that matters there.
8. Review before delivering: run an adversarial pass with a second agent or model if your environment has one, otherwise do a fresh self-review. Give the reviewer the verified facts and have it attack four things: claims beyond the facts, unglossed jargon, anything overwhelming for a beginner, and dramatic language. The reviewer may also flag true facts it was not given; check those against your evidence instead of "fixing" them.
9. Write and save the report through the seo-report skill (see Output format).

Output format

h1: the domain. Then one or two opening sentences: the overall state and the one thing.

If a report template applies (see seo-report), its sections and tone replace this list.

Sections in this order:

1. Verdict — three to five bullets, one line each: the state of the site, the numbers that matter (pages crawled and indexable, search terms and estimated visits, linking sites), and the biggest gap. No prose.
2. Top priority — one finding, with copy-paste-ready mechanics.
3. Small fixes — one finding each, 5 to 10 max, ordered by impact. Each shows the exact evidence: a quoted tag, a number, or a URL.
4. Where to focus first (healthy sites only) — one sentence, then a table of 3 to 5 keywords with volume and difficulty and the page or post to make for each, plus a bar chart when the volumes are worth comparing. Omit the whole section when the site is down.
5. What's working now — a short list.
6. What to do next — an ordered list, the one thing first.
7. How this report was made — opens with the skill link line from seo-report, pointing at https://openseo.so/docs/skills/seo-audit ("OpenSEO SEO Audit skill"), then what the tools reported and what you verified by hand.

Use a note for anything you could not verify or where the site's goal makes a standard recommendation the wrong call.

Guardrails

• Tone: calm and plain. No exclamation points, no drama words, no em dashes, no "Not X. Y." contrasts, no filler. Severity words only where literally true (a down site is critical; a long title is not).
• Gloss every term of art in plain English on first use: canonical, meta description, alt text, crawler, 301, structured data.
• Skip nitpicks that do not matter for the specific site. A beginner report with twenty findings has failed.
• Missing backlink or ranking data means "no recorded data", not a penalty; say so rather than dramatizing it.
• Favor keywords the site can win now: specific intent, low difficulty. Do not list head terms a new site cannot rank for yet.
• Separate what the tools reported from what you verified yourself, and note both in the method footer.