From 68fdcd9bf9eb8f2f6582ae148e2f17ea871b1830 Mon Sep 17 00:00:00 2001 From: Ben Senescu <44480372+bensenescu@users.noreply.github.com> Date: Wed, 29 Jul 2026 20:47:14 -0400 Subject: [PATCH] feat(skills): add seo-audit agent skill (#430) * feat(skills): add beginner-seo-audit agent skill A portable agent skill that audits a domain with OpenSEO and delivers a one-page, plain-language HTML report for a non-SEO owner, centered on a single do-this-week action. Ships with a frozen report template and a docs page under Agent Skills. * feat(skills): add starting-focus keyword step; cross-link from coach and project setup - beginner-seo-audit now proposes a 'Where to focus first' area on healthy sites: one research_keywords call, one theme, 3-5 winnable keywords with what to make for each. Skipped entirely when the site is down. - seo-coach and seo-project-setup now recommend beginner-seo-audit as the first workflow for a beginner with an existing site. - Docs pages updated to match. * refactor(skills): rename beginner-seo-audit to seo-audit Audience-neutral name; the plain-language, one-action framing moves to the description. Docs slug, meta.json, and coach/project-setup cross-references updated to match. --- .agents/skills/seo-audit/SKILL.md | 63 ++++++++ .agents/skills/seo-audit/template.html | 136 ++++++++++++++++++ .agents/skills/seo-coach/SKILL.md | 3 + .agents/skills/seo-project-setup/SKILL.md | 1 + web/content/docs/skills/index.md | 4 + web/content/docs/skills/meta.json | 1 + web/content/docs/skills/seo-audit.mdx | 56 ++++++++ web/content/docs/skills/seo-coach.mdx | 1 + web/content/docs/skills/seo-project-setup.mdx | 1 + 9 files changed, 266 insertions(+) create mode 100644 .agents/skills/seo-audit/SKILL.md create mode 100644 .agents/skills/seo-audit/template.html create mode 100644 web/content/docs/skills/seo-audit.mdx diff --git a/.agents/skills/seo-audit/SKILL.md b/.agents/skills/seo-audit/SKILL.md new file mode 100644 index 0000000..0da5a1a --- /dev/null +++ b/.agents/skills/seo-audit/SKILL.md @@ -0,0 +1,63 @@ +--- +name: seo-audit +description: "Audit a website and deliver a one-page, plain-language SEO report anyone can act on, centered on a single do-this-week action." +--- + +# 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`) + +## 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), 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. + +## Output format + +Use `template.html` next to this file. Fill in content; keep the CSS and structure as they are (light palette only, no dark mode). + +- Header: domain as the title, the review date on its own line under it, then a 2-3 sentence summary of the whole report (overall state; the main gap and the one thing; what the report covers). +- Section order: verdict, the one thing, small fixes (5 to 10 max, ordered by impact), where to focus first (healthy sites only), already working, method footer. +- Each fix row shows the exact evidence (a quoted tag or number) and concrete steps a non-technical person can follow. +- "Where to focus first" names one topic area and 3 to 5 keywords, each with its search volume in plain words and the page or post to make. Omit the section when the site is down. + +## 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. diff --git a/.agents/skills/seo-audit/template.html b/.agents/skills/seo-audit/template.html new file mode 100644 index 0000000..933e897 --- /dev/null +++ b/.agents/skills/seo-audit/template.html @@ -0,0 +1,136 @@ + + + + + + +DOMAIN SEO review + + + +
+
+

DOMAIN

+

DATE

+

SUMMARY: 2-3 sentences covering the whole report. Sentence 1: overall state of the site. Sentence 2: the main gap and the one thing. Sentence 3: what the report covers.

+
+ +
+

Where the site stands

+

VERDICT-PARAGRAPH: what is working, in plain words.

+

VERDICT-PARAGRAPH-2: the main gap the one thing addresses.

+
+ +
+ +
+

If you only do one thing

+

THE-ONE-THING, one sentence.

+

WHY-IT-MATTERS, one or two sentences.

+
    +
  1. STEP-1 (concrete, doable today).
    2. +
  2. STEP-2 (include any copy-paste message in italics).
    3. +
  3. STEP-3 (how to check it worked).
    4. +
+
+ +
+

Small fixes, in order

+ +
+

FINDING-TITLE low

+
+

WHAT-WE-FOUND with the exact evidence, e.g. a quoted tag in code.

+

Fix: CONCRETE-STEPS a non-technical person can follow.

+
+
+
+ +
+

Where to focus first

+ +

FOCUS-INTRO: the one topic area to build toward and why it fits this site.

+
+

KEYWORD N searches/mo

+
+

WHY-THIS-KEYWORD: who searches it and how winnable it is, in plain words.

+

Make: WHAT-TO-CREATE, one page or post and its angle.

+
+
+
+ +
+

Already working

+ +
+ + +
+ + diff --git a/.agents/skills/seo-coach/SKILL.md b/.agents/skills/seo-coach/SKILL.md index 8688416..b9f0b82 100644 --- a/.agents/skills/seo-coach/SKILL.md +++ b/.agents/skills/seo-coach/SKILL.md @@ -29,6 +29,7 @@ I can coach you through this. Are you new to SEO, or do you mostly want help usi Good starting points: - Set up SEO project context +- Get a one-page audit of your site - Find keyword opportunities - Map keywords to pages - Study a competitor @@ -38,6 +39,7 @@ Good starting points: ## What each workflow does - `seo-project-setup`: sets up the workspace, verifies MCP, captures goals and positioning, and connects Google Search Console (or imports GSC exports). +- `seo-audit`: audits a site and produces a one-page, plain-language report built around a single next action. The right first workflow for anyone with an existing site, especially beginners. - `keyword-research`: finds search opportunities from seed topics and evaluates volume, difficulty, CPC, intent, and SERPs. - `keyword-clustering`: groups keywords by intent and maps clusters to existing or proposed pages. - `competitive-landscape`: identifies who wins across a market and what content/backlink patterns are working. @@ -93,6 +95,7 @@ When the user asks for execution: Offer concise options based on context: - "Let's set up project context first." +- "Let's audit your site and find the one thing to do first." - "Let's research keywords from your seed topics." - "Let's cluster your GSC/query export into page targets." - "Let's map the competitive landscape before choosing pages." diff --git a/.agents/skills/seo-project-setup/SKILL.md b/.agents/skills/seo-project-setup/SKILL.md index 9101f14..688397e 100644 --- a/.agents/skills/seo-project-setup/SKILL.md +++ b/.agents/skills/seo-project-setup/SKILL.md @@ -134,6 +134,7 @@ Ask for or discover: After intake, recommend one next OpenSEO workflow: +- `seo-audit`: when the site already exists and the user wants to know what to fix or do first, especially if they are new to SEO - `keyword-research`: when the user needs ideas from seed topics - `keyword-clustering`: when they have keywords or GSC data to map to pages - `competitive-landscape`: when the market is unclear diff --git a/web/content/docs/skills/index.md b/web/content/docs/skills/index.md index 1cc172f..5799d74 100644 --- a/web/content/docs/skills/index.md +++ b/web/content/docs/skills/index.md @@ -21,6 +21,10 @@ MCP connects your agent to OpenSEO data. Skills tell your agent which SEO workfl - [SEO Project Setup](/docs/skills/seo-project-setup): set up a durable project workspace so your agent can reuse goals, context, exports, and preferences across sessions. - [SEO Coach](/docs/skills/seo-coach): choose the next workflow when you are new to SEO or unsure what to run first. +## Audit workflows + +- [SEO Audit](/docs/skills/seo-audit): audit a site and get a one-page, plain-language report built around a single next action. + ## Research workflows - [Keyword Research](/docs/skills/keyword-research): find keywords worth targeting and explain why they fit. diff --git a/web/content/docs/skills/meta.json b/web/content/docs/skills/meta.json index f4f0360..08bfc95 100644 --- a/web/content/docs/skills/meta.json +++ b/web/content/docs/skills/meta.json @@ -5,6 +5,7 @@ "[Install Agent Skills](/docs/skills/setup)", "[Project Setup](/docs/skills/seo-project-setup)", "[SEO Coach](/docs/skills/seo-coach)", + "[SEO Audit](/docs/skills/seo-audit)", "[Keyword Research](/docs/skills/keyword-research)", "[Keyword Clustering](/docs/skills/keyword-clustering)", "[Competitive Landscape](/docs/skills/competitive-landscape)", diff --git a/web/content/docs/skills/seo-audit.mdx b/web/content/docs/skills/seo-audit.mdx new file mode 100644 index 0000000..f4770dd --- /dev/null +++ b/web/content/docs/skills/seo-audit.mdx @@ -0,0 +1,56 @@ +--- +title: "SEO Audit Agent Skill" +description: "Audit a website with your AI agent and get a one-page, plain-language SEO report built around a single next action." +--- + + + +The SEO Audit Agent Skill audits a site and writes a one-page HTML report that anyone can act on, including someone who has never done SEO. + +Your agent runs an OpenSEO site audit, pulls backlink and traffic-estimate data, and re-checks every finding against the live pages before reporting it. The report is built around one action the site owner can take this week, with the exact message or steps included, followed by a short list of small fixes and a section on what already works. + +The skill is plain `SKILL.md` instructions plus an HTML template, so it runs in Claude Code, Codex, or any agent that supports the skills format. If your agent can publish or preview HTML it will use that; otherwise it saves the report as a file for you to open in your browser. + +## What this skill helps your agent do + +- Run a site audit and read the prioritized issues. +- Check backlinks and traffic estimates to find the real bottleneck, not just tag-level nitpicks. +- Verify each finding against the live page HTML before reporting it. +- Pick one do-this-week action and include the copy-paste mechanics for it. +- Propose a starting focus area: a handful of specific, winnable keywords and what to make for each. +- Explain every technical term in plain English the first time it appears. +- Deliver the result as a single HTML page you can send to anyone. + +## When to use it + +Use this skill when the report is for someone new to SEO: a client, a founder, a friend with a podcast or a photography site. It is also a good first skill if that beginner is you, because the report explains itself. + +It handles broken sites honestly. If the domain is down or half-crawled, the agent investigates why before writing, and the recommendation changes to match: an expired certificate, a dead domain with a live successor site, or a page-level block each lead to a different "one thing". + +## What you get back + +One HTML page: a three-sentence summary, the single action to take this week with concrete steps, five to ten small fixes with the exact evidence for each, a starting focus area with three to five keyword ideas (healthy sites only), a list of what already works, and a note on how the review was done. + +## How to get the best result + +- Give the agent one domain. +- Say who the report is for. +- Mention anything you already know, like a site move or an old domain. +- Ask to see the verified facts if you want to check the agent's work. + +## Use it with OpenSEO MCP + +Set up [OpenSEO MCP](/docs/mcp) so your agent can run the audit and read backlink data, traffic estimates, and keyword ideas. The site audit is included on every plan (up to 50 pages on the free plan); the backlink, domain, and keyword lookups spend credits, and the skill keeps that spend modest. + +## Read the actual skill + +The source `SKILL.md` lives on GitHub: + +- [SEO Audit skill](https://github.com/every-app/open-seo/tree/main/.agents/skills/seo-audit) + +## Related skills + +- [SEO Coach](/docs/skills/seo-coach) if you are not sure this is the right workflow to run first. +- [Keyword Research](/docs/skills/keyword-research) to go deeper than the report's starting keywords. +- [Link Prospecting](/docs/skills/link-prospecting) when the report's one thing is links and you want to go beyond the first outreach batch. +- [Competitor Analysis](/docs/skills/competitor-analysis) once the basics are handled and you want to study who outranks you. diff --git a/web/content/docs/skills/seo-coach.mdx b/web/content/docs/skills/seo-coach.mdx index 255d1ff..06c4ced 100644 --- a/web/content/docs/skills/seo-coach.mdx +++ b/web/content/docs/skills/seo-coach.mdx @@ -54,5 +54,6 @@ The source `SKILL.md` lives on GitHub: ## Related skills - [SEO Project Setup](/docs/skills/seo-project-setup) when you need setup and project context. +- [SEO Audit](/docs/skills/seo-audit) when you have a site and want a plain-language report on what to do first. - [Keyword Research](/docs/skills/keyword-research) when you are ready to find opportunities. - [Competitive Landscape](/docs/skills/competitive-landscape) when the market is unclear. diff --git a/web/content/docs/skills/seo-project-setup.mdx b/web/content/docs/skills/seo-project-setup.mdx index 539c6aa..c15bdb5 100644 --- a/web/content/docs/skills/seo-project-setup.mdx +++ b/web/content/docs/skills/seo-project-setup.mdx @@ -51,5 +51,6 @@ The source `SKILL.md` lives on GitHub: ## Related skills - [SEO Coach](/docs/skills/seo-coach) if you are new to SEO or unsure where to start. +- [SEO Audit](/docs/skills/seo-audit) once setup is done and you want a plain-language report on what to do first. - [Keyword Research](/docs/skills/keyword-research) when you are ready to find search opportunities. - [Competitive Landscape](/docs/skills/competitive-landscape) when you need to understand the market first.