upgradeseo: Skill for Claude Code

UpgradeSEO 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)

UpgradeSEO MCP tools

• whoami: confirm connection and remaining credits before spending anything. If UpgradeSEO 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), then poll get_audit_status 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. 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. Write the report using template.html in this skill directory (see Output format).
9. 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.
10. Deliver the report: if your environment can publish or preview HTML (for example as an artifact), do that; otherwise save the HTML file and tell the user to open it in their browser.