Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
Rewrite the SEO audit skill around a shortlist-then-choose workflow (#647)
Ben Senescu0ffff9310104
diff --git a/.agents/skills/evaluate-skill/SKILL.md b/.agents/skills/evaluate-skill/SKILL.mdnew file mode 100644index 00000000..6a18a492--- /dev/null+++ b/.agents/skills/evaluate-skill/SKILL.md@@ -0,0 +1,89 @@+---+name: evaluate-skill+description: "Test a candidate OpenSEO skill end to end by running fresh, isolated Codex sessions against the local backend and scoring the reports they save. Use when editing a product skill (seo-audit, keyword-research, ...) and you need evidence that the new instructions produce better output, not just a cleaner file."+metadata:+ internal: true+---++# Evaluate a skill++A skill edit is only as good as the reports it produces. This workflow runs the candidate skill in sessions that know nothing except the skill file, a one-line business brief, and a locked-down local MCP endpoint, then compares what came back.++## Prerequisites++- Local server in no-auth mode: `AUTH_MODE=local_noauth` in `.env.local`, then `pnpm db:migrate:local` and `pnpm dev` (or `pnpm dev:agents`). Pass the URL it prints, with `/mcp` appended, as `--endpoint`. Default local D1, never remote bindings or remote Postgres. Keep it private; it has no login.+- `codex` CLI on the path. Runs use its configured default model at high reasoning; record the resolved model from the events log if you need to name it.+- Research credits: the local server still calls DataForSEO. An audit run makes 20 to 40 tool calls. Do not run more sessions than the comparison needs.++## Run++```sh+node .agents/skills/evaluate-skill/scripts/run.mjs \+ --skill seo-audit \+ --site example.com --site holdout.example \+ --brief "Evaluation brief: Acme at example.com sells <what>. The goal is relevant organic visitors who could become customers. No first-party analytics are connected." \+ --brief "Evaluation brief: <the holdout business>. ..." \+ --endpoint http://<local-dev-host>/mcp+```++Runs take about 10 to 14 minutes and execute in parallel. Launch the script detached, because a tool-call timeout that kills the shell kills the sessions too:++```sh+(nohup node .agents/skills/evaluate-skill/scripts/run.mjs ... > .logs/eval.log 2>&1 &)+```++What the script does, per site:++1. Copies the candidate skill and `seo-report` into a fresh temp folder. Edits during the run cannot change its instructions; the manifest records the skill hashes.+2. Creates a new local project seeded only with the brief.+3. Starts a gateway in front of the local MCP that allows a fixed tool list and rejects any call for another project id, then probes that rejection before starting.+4. Runs `codex exec` ephemeral, ignoring user config, memories, apps, plugins, and multi-agent, with the skill's self-review as the only reviewer.+5. Captures the saved report HTML, every MCP call and response, the event stream, and the final message under the output folder.++Read the reports with `node .agents/skills/evaluate-skill/scripts/report-text.mjs <out>/*-report.html`. Each session's working notes (for seo-audit, `opportunities.md` and `evidence/`) stay in its temp folder, named in `manifest.json`.++## Isolation rules++- **Instructions:** frozen copies only. Never point a session at the working tree.+- **Conversation:** a new `codex exec` per run. Never resume or fork.+- **Data:** a new project per run, seeded with the user-provided brief and nothing else. Never write evaluator notes, prior reports, or a reference answer into any project the sessions can read.+- **Prompt:** the same neutral prompt for every variant. Do not name expected findings, target keywords, or the rubric.+- **Evaluator material** (rubric, reference audits, prior reports) lives outside the session folders and outside the repository. Raw artifacts belong in the ignored `.logs/`.++This is practical isolation, not a security boundary: sessions share the local account, provider caches, and organization limits.++## Compare++Always run at least two sessions of the site you are tuning on and one holdout site with a different shape, so an instruction that fits one company's answer is caught. Keep every run, including failures; do not pick the best of several and call the skill fixed.++Score each report before opening its tool trace, then read the trace to classify any miss as discovery, tool, reasoning, or reporting. For an audit report:++| Dimension | Weight | A strong report... |+| ------------------------------- | -----: | ------------------------------------------------------------------------------------------------------------------ |+| Discovery and coverage | 25% | Reads commercial pages and their siblings, tools, and technical paths; broadens when a signal appears |+| Diagnosis and evidence | 20% | Checks live pages and live results; separates observations from causes; records source, date, and settings |+| Business value and scale | 20% | Ties each action to a real buyer; compares competing opportunities; never invents conversion or revenue |+| Prioritization | 15% | Leads with a bounded change to a demonstrated problem for likely buyers; keeps maintenance and broad programs back |+| Calibration | 10% | Makes useful calls without analytics; no penalty, causation, or trend claims the evidence cannot carry |+| Communication and actionability | 10% | Names the page, the change, and the reason; material findings survive compression |++A material factual error overrides the score. Ask a second model to recompute every live position from the run's own MCP log before trusting a report's numbers.++Coverage checks that generalize beyond any one site:++- Sibling pages in an important family (comparison, pricing, template, location) were read side by side, and a page that only swaps a name into a shared answer was noticed.+- A page already at the top for its query was protected, not rewritten.+- Every serious candidate ended as a recommendation or as a table row with a real reason. A vague "later" is a miss.+- Search volume, visits, and revenue were kept distinct; US demand was not multiplied into a global figure.++## What past evaluations taught++- **Instruction length hurts.** A 3,600-word skill of cautions performed worse than a 2,200-word skill with a fixed process. Add a step, not a warning.+- **Force the comparison.** Sessions that wrote a shortlist before drafting kept their diagnoses; sessions that drafted straight from research ranked by raw query volume.+- **Show the rejected candidates.** A "What else we checked" table in the report is what stops material findings from disappearing when the report is shortened.+- **One snapshot lies.** Positions around 8 to 12 change between two checks minutes apart; the skill re-runs decisive queries and reports both.+- **Labels beat notes.** Readers rejected "10th of 17 organic rows" and arrows; tables now say "#10 (page 1)" with market and date in the header.++## Clean up++Each run's project, report, and audit can be removed through MCP with `delete_report`, `delete_site_audit`, and `update_project_context`, or left in the local database. A new project per run is simpler than proving an old one is clean. Stop the local server when finished.diff --git a/.agents/skills/evaluate-skill/scripts/report-text.mjs b/.agents/skills/evaluate-skill/scripts/report-text.mjsnew file mode 100644index 00000000..198cc0fa--- /dev/null+++ b/.agents/skills/evaluate-skill/scripts/report-text.mjs@@ -0,0 +1,30 @@+#!/usr/bin/env node+// Print a saved report's HTML as readable text, main body first, so reports+// can be compared without opening the app. Usage: node report-text.mjs <file>...+import { readFile } from "node:fs/promises";++const decode = (s) =>+ s+ .replace(/ /g, " ")+ .replace(/&/g, "&")+ .replace(/</g, "<")+ .replace(/>/g, ">")+ .replace(/"/g, '"')+ .replace(/'|’|‘/g, "'")+ .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)));++for (const file of process.argv.slice(2)) {+ let s = await readFile(file, "utf8");+ s = s.replace(/<style[\s\S]*?<\/style>/g, "");+ s = s.replace(/<h[1-3][^>]*>/g, "\n## ");+ s = s.replace(/<(li|tr|p|summary)[^>]*>/g, "\n- ");+ s = s.replace(/<(td|th)[^>]*>/g, " | ");+ s = s.replace(/<details/g, "\n[DETAILS]<details");+ s = decode(s.replace(/<[^>]+>/g, "")).replace(/\n\s*\n+/g, "\n");+ const main = s.split("[DETAILS]")[0];+ const words = (t) => t.split(/\s+/).filter(Boolean).length;+ console.log(+ `${"=".repeat(30)} ${file} | total words ${words(s)} | main-body words ${words(main)}`,+ );+ console.log(s);+}diff --git a/.agents/skills/evaluate-skill/scripts/run.mjs b/.agents/skills/evaluate-skill/scripts/run.mjsnew file mode 100644index 00000000..9721a55a--- /dev/null+++ b/.agents/skills/evaluate-skill/scripts/run.mjs@@ -0,0 +1,339 @@+#!/usr/bin/env node+// Run fresh, isolated Codex sessions against a candidate skill on the local+// OpenSEO backend. One session per --site, all in parallel. See ../SKILL.md.+//+// node .agents/skills/evaluate-skill/scripts/run.mjs \+// --skill seo-audit --site example.com --site holdout.example \+// --endpoint http://<local-dev-host>/mcp [--brief "..."] [--out .logs/skill-eval-<ts>]+//+// Each run gets: a frozen copy of the skill (plus seo-report) in a fresh /tmp+// folder, a new local project seeded only with the brief, and a per-run MCP+// gateway that allows a fixed tool list and rejects any other project id.+// Artifacts land in --out: manifest.json, <run>-report.html, <run>-mcp.jsonl,+// <run>-events.jsonl, <run>-result.md, run.log.++import { createServer } from "node:http";+import { spawn } from "node:child_process";+import { mkdir, readFile, writeFile, appendFile, cp } from "node:fs/promises";+import { createWriteStream } from "node:fs";+import { createHash } from "node:crypto";+import { mkdtemp } from "node:fs/promises";+import { tmpdir } from "node:os";+import path from "node:path";++const args = process.argv.slice(2);+const opt = (name, fallback) => {+ const i = args.indexOf(name);+ return i === -1 ? fallback : args[i + 1];+};+const all = (name) =>+ args.flatMap((a, i) => (a === name ? [args[i + 1]] : []));++const skill = opt("--skill", "seo-audit");+const sites = all("--site");+const briefs = all("--brief");+const upstream = opt("--endpoint");+const stamp = new Date().toISOString().replace(/[:.]/g, "-");+const out = path.resolve(opt("--out", `.logs/skill-eval-${stamp}`));+if (sites.length === 0 || !upstream) {+ console.error("Pass --endpoint <local MCP URL> and at least one --site <domain>");+ process.exit(1);+}++const allowed = new Set([+ "whoami",+ "get_project_context",+ "update_project_context",+ "run_site_audit",+ "get_audit_status",+ "get_audit_issues",+ "get_audit_pages",+ "get_domain_overview",+ "get_ranked_keywords",+ "get_backlinks_overview",+ "get_backlinks_profile",+ "get_keyword_metrics",+ "research_keywords",+ "get_serp_results",+ "get_search_console_performance",+ "list_reports",+ "get_report",+ "list_report_templates",+ "save_report",+]);++let seq = 0;+async function rpc(name, params) {+ const r = await fetch(upstream, {+ method: "POST",+ headers: {+ "content-type": "application/json",+ accept: "application/json, text/event-stream",+ },+ body: JSON.stringify({+ jsonrpc: "2.0",+ id: ++seq,+ method: "tools/call",+ params: { name, arguments: params },+ }),+ });+ const d = await r.json();+ if (d.error || d.result?.isError) throw new Error(JSON.stringify(d));+ return d.result.structuredContent;+}++const sha = async (p) =>+ createHash("sha256")+ .update(await readFile(p))+ .digest("hex");++await mkdir(out, { recursive: true });+const identity = await rpc("whoami", {});+if (identity.mode !== "self-hosted") {+ console.error("Refusing to run against a non-local backend:", identity);+ process.exit(1);+}++const workspace = await mkdtemp(path.join(tmpdir(), "openseo-skill-eval-"));+const manifest = {+ skill,+ upstream,+ workspace,+ startedAt: new Date().toISOString(),+ model: "Codex CLI configured default, no override",+ reasoning: "high",+ skillHash: await sha(`.agents/skills/${skill}/SKILL.md`),+ reportSkillHash: await sha(".agents/skills/seo-report/SKILL.md"),+ runs: {},+};++for (const [i, domain] of sites.entries()) {+ const name = `${domain.replace(/[^a-z0-9]+/gi, "-")}-${i + 1}`;+ const folder = path.join(workspace, name);+ await mkdir(path.join(folder, ".agents/skills"), { recursive: true });+ for (const s of new Set([skill, "seo-report"])) {+ await cp(`.agents/skills/${s}`, path.join(folder, ".agents/skills", s), {+ recursive: true,+ });+ }+ const brief =+ briefs[i] ??+ briefs[0] ??+ `Evaluation brief: the business at ${domain}. Verify its offering and audience from the public website. The goal is to attract relevant organic visitors who could become customers. No first-party analytics are connected.`;+ const project = await rpc("create_project", {+ name: `Skill eval ${skill} ${name} ${manifest.startedAt}`,+ domain,+ locationCode: 2840,+ languageCode: "en",+ });+ const projectId = project.project.id;+ await rpc("update_project_context", {+ projectId,+ updates: [{ section: "business_overview", content: brief }],+ });+ manifest.runs[name] = { domain, brief, folder, projectId };+}+await writeFile(+ path.join(out, "manifest.json"),+ JSON.stringify(manifest, null, 2),+);++async function start(name, run) {+ const log = path.join(out, `${name}-mcp.jsonl`);+ let calls = 0;+ let failures = 0;+ const gateway = createServer(async (req, res) => {+ try {+ const chunks = [];+ for await (const c of req) chunks.push(c);+ const body = Buffer.concat(chunks).toString();+ const input = body ? JSON.parse(body) : null;+ if (req.method !== "POST" || !input) {+ res.writeHead(405);+ res.end();+ return;+ }+ const reply = (payload) => {+ res.writeHead(200, { "content-type": "application/json" });+ res.end(JSON.stringify(payload));+ };+ if (input.method === "tools/call") {+ const { name: tool, arguments: a = {} } = input.params ?? {};+ if (+ !allowed.has(tool) ||+ (tool !== "whoami" && a.projectId !== run.projectId)+ ) {+ await appendFile(+ log,+ JSON.stringify({ at: new Date().toISOString(), blocked: true, input }) ++ "\n",+ );+ reply({+ jsonrpc: "2.0",+ id: input.id,+ result: {+ isError: true,+ content: [+ {+ type: "text",+ text: "This evaluation endpoint only allows approved tools for the assigned project.",+ },+ ],+ },+ });+ return;+ }+ } else if (+ !["initialize", "notifications/initialized", "ping", "tools/list"].includes(+ input.method,+ )+ ) {+ reply({+ jsonrpc: "2.0",+ id: input.id,+ error: { code: -32601, message: "Method unavailable in evaluation" },+ });+ return;+ }+ const up = await fetch(upstream, {+ method: "POST",+ headers: {+ "content-type": "application/json",+ accept: "application/json, text/event-stream",+ },+ body: JSON.stringify(input),+ signal: AbortSignal.timeout(240000),+ });+ const raw = await up.text();+ const data = raw ? JSON.parse(raw) : null;+ if (input.method === "tools/list" && data?.result?.tools) {+ data.result.tools = data.result.tools.filter((t) => allowed.has(t.name));+ }+ if (input.method === "tools/call") {+ calls++;+ if (data?.error || data?.result?.isError) failures++;+ await appendFile(+ log,+ JSON.stringify({ at: new Date().toISOString(), input, response: data }) ++ "\n",+ );+ if (input.params.name === "save_report" && !data?.result?.isError) {+ await writeFile(+ path.join(out, `${name}-report.html`),+ input.params.arguments.html,+ );+ await writeFile(+ path.join(out, `${name}-saved.json`),+ JSON.stringify(data.result.structuredContent, null, 2),+ );+ }+ }+ res.writeHead(up.status, { "content-type": "application/json" });+ res.end(data ? JSON.stringify(data) : "");+ } catch (e) {+ res.writeHead(500, { "content-type": "application/json" });+ res.end(JSON.stringify({ error: String(e) }));+ }+ });+ await new Promise((resolve) => gateway.listen(0, "127.0.0.1", resolve));+ run.endpoint = `http://127.0.0.1:${gateway.address().port}/mcp`;++ const probe = await fetch(run.endpoint, {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify({+ jsonrpc: "2.0",+ id: 999,+ method: "tools/call",+ params: {+ name: "get_project_context",+ arguments: { projectId: "different-project" },+ },+ }),+ });+ if (!(await probe.json()).result?.isError) throw new Error("Isolation probe failed");++ const prompt = `Use the supplied .agents/skills/${skill}/SKILL.md and .agents/skills/seo-report/SKILL.md to work on https://${run.domain}. Read those exact local files. Produce a useful result with enough investigation to support your conclusions.++Your only OpenSEO project is ${run.projectId}. Its local MCP endpoint is ${run.endpoint}. You are authorized to perform the research and save a completed report there. Do not access any other OpenSEO project or production app/connector. Do not read prior reports, evaluator materials, personal memories, or files outside this working folder. Use only these supplied skills; do not substitute a globally installed skill.++The project's business brief is sufficient to start. Verify details from the website; if further business details are unavailable, state reasonable assumptions and continue without questions. First-party analytics are not connected. External public-web reading is allowed. Do not submit forms or alter the audited website.++Save evidence and notes inside this working folder. Deliver the report using local save_report and include its link in your final answer. Do not edit the supplied skills. If no second reviewer tool is available, perform the skill's self-review.+`;+ await writeFile(path.join(run.folder, "prompt.txt"), prompt);+ const codexArgs = [+ "exec",+ "--ignore-user-config",+ "--ephemeral",+ "--skip-git-repo-check",+ "--cd",+ run.folder,+ "--sandbox",+ "workspace-write",+ "--disable",+ "apps",+ "--disable",+ "plugins",+ "--disable",+ "multi_agent",+ "-c",+ "memories.use_memories=false",+ "-c",+ "memories.generate_memories=false",+ "-c",+ 'model_reasoning_effort="high"',+ "-c",+ "sandbox_workspace_write.network_access=true",+ "-c",+ 'web_search="live"',+ "-c",+ `mcp_servers.openseo-local.url=${JSON.stringify(run.endpoint)}`,+ "-c",+ "mcp_servers.openseo-local.required=true",+ "-c",+ 'mcp_servers.openseo-local.default_tools_approval_mode="approve"',+ "--json",+ "--output-last-message",+ path.join(run.folder, "result.md"),+ "-",+ ];+ const child = spawn("codex", codexArgs, {+ cwd: run.folder,+ stdio: ["pipe", "pipe", "pipe"],+ });+ run.startedAt = new Date().toISOString();+ child.stdout.pipe(createWriteStream(path.join(out, `${name}-events.jsonl`)));+ child.stderr.pipe(createWriteStream(path.join(out, `${name}-stderr.log`)));+ child.stdin.end(prompt);+ console.log("START", name, "project", run.projectId);+ const timer = setInterval(+ () => console.log("PROGRESS", name, calls, "MCP calls", failures, "errors"),+ 30000,+ );+ const code = await new Promise((resolve, reject) => {+ child.on("exit", resolve);+ child.on("error", reject);+ });+ clearInterval(timer);+ Object.assign(run, {+ finishedAt: new Date().toISOString(),+ exitCode: code,+ mcpCalls: calls,+ mcpErrors: failures,+ });+ gateway.close();+ try {+ await cp(path.join(run.folder, "result.md"), path.join(out, `${name}-result.md`));+ } catch {+ // no final message; the events log still has the run+ }+ console.log("DONE", name, "exit", code, "calls", calls, "errors", failures);+}++await Promise.all(Object.entries(manifest.runs).map(([n, r]) => start(n, r)));+await writeFile(+ path.join(out, "manifest.json"),+ JSON.stringify(manifest, null, 2),+);+console.log("ALL RUNS COMPLETE", out);diff --git a/.agents/skills/seo-audit/SKILL.md b/.agents/skills/seo-audit/SKILL.mdindex 1a41c92d..eb1cb0e4 100644--- a/.agents/skills/seo-audit/SKILL.md+++ b/.agents/skills/seo-audit/SKILL.md@@ -1,84 +1,140 @@---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."+description: "Audit a website, investigate its real search opportunities, and deliver a short data-backed report on the few changes most likely to grow organic traffic that converts."---# 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.+Find the work that would most improve a site's useful organic traffic, then explain it so a non-expert can act on it. Research broadly; recommend selectively. The report leads with one to three recommendations that either capture meaningfully more qualified search demand or stop a real loss.-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.+Use this when asked for an SEO audit or review of a domain, especially for a shareable report. For expert-facing analysis of a competitor or market, use `competitor-analysis` or `competitive-landscape` instead.-## Required inputs+## Inputs and project context-- Domain to audit-- `projectId` (use `list_projects`; if no project matches the domain, create one with `create_project`)+- Domain to audit and `projectId` (`list_projects`; if no project matches, `create_project`).+- Call `get_project_context` first. This skill needs `business_overview`. If it is empty, infer what the business does from the site, confirm it with the user in one question, write it back with `update_project_context`, and continue. Suggest `seo-project-setup` at the end for the rest; never front-load the full interview.+- Reuse research-log results under 30 days old for discovery. A ranking claim that drives a recommendation still needs a live check made during this audit.+- On finish, write back what is durable with `update_project_context` (a corrected `business_overview`, the pages the report names via `addKeyPages`) and append `{ appendResearchLog: { summary: "Site audit: <domain>. Verdict: <conclusion>" } }`.-## Project context+Deliver through the `seo-report` skill, saving with `skill: "seo-audit"`. If that skill is unavailable, say so and stop before writing HTML.-The project-context tools are free and shared with the app and other agents.+## OpenSEO MCP tools-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>" } }`.+- `whoami`: confirm the connection and credits before spending. If OpenSEO is not connected, stop and ask the user to connect it.+- `run_site_audit`, then `get_audit_status` (wait a minute or two between checks), `get_audit_issues`, `get_audit_pages`. Leave Lighthouse off unless the user asked for performance depth. Crawl reads are free.+- `get_backlinks_overview` and `get_domain_overview`: orientation only. Provider traffic and keyword counts are estimates with no single observation date; they are not measured visits.+- `get_ranked_keywords`: which queries send which pages traffic. Start with one domain-level call with `resultTypes: ["organic"]`; use `scope: "exact_url"` for the specific pages you compare. A page missing from a limited domain sample is not proof it has no rankings. Ranking rows carry their own `last_updated_time`; keyword metric dates are not ranking dates.+- `get_serp_results`: the live check behind every ranking claim in the report. The returned `rank` counts every result block, so count organic (unpaid) listings yourself and report the spot with its page, ten spots per page: "#10 (page 1)", "#11 (page 2)". Request depth 20; a page not seen is "not in the first 20 results". Record the exact query, country, language, date, how many organic listings came back, and the matching URL; those details go in the evidence appendix, not the tables. A failed lookup is unknown, not "not in the first 20 results".+- `get_search_console_performance`: when connected, first-party clicks and impressions separate low visibility from low click-through. Missing access is a coverage gap, not a blocker.+- `get_keyword_metrics` and `research_keywords`: demand for the queries a candidate page targets. One focused metrics batch usually suffices; one research call with 1–3 seeds when a demand gap could change the decision.+- Web reading (fetch, scrape, or search): the site's own pages, sitemap, the leading results for a query, and competitor pages.-## Deliver as a report+Research until another lookup is unlikely to change which opportunities lead. Respect an explicit user budget and say which comparison it prevented.-Deliver through the `seo-report` skill, saving with `skill: "seo-audit"`. If that skill is not available, say so and stop before writing HTML.+## Workflow-## OpenSEO MCP tools+### 1. Orient-- `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.+`whoami`, resolve the project, start `run_site_audit`. While it crawls: backlinks overview, domain overview, the domain-level ranked-keyword sample, and the sitemap plus navigation. Write down the site's page families from the sitemap, not just the crawl sample: product, pricing, comparison or alternative, tools and templates, guides, categories, services, locations, whatever the site actually has.-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.+If the crawl is broken or nearly empty (certificate error, 5xx, one page), investigate before anything else. Check redirects and certificate variants yourself and search for the business; a dead domain with a live successor flips the whole recommendation to "redirect the old domain".-## Workflow+### 2. Investigate every family that matters to the goal-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).+For each family that could bring buyers, read at least two pages' main content (ignore navigation and shared templates): the page performing best in the ranking data and one performing worst or typical. For each page ask: what decision or question does its searcher have, and does the page answer it with specific, accurate, sourced information, or does it substitute a name, location, or keyword into a shared answer? Compare against what the leading results for that query provide.-## Output format+A common SaaS pattern worth checking directly: competitor comparison or alternative pages and competitor pricing pages are two separate families, each answering a different buying question. Read siblings side by side. Investigate uneven visibility between siblings (intent, content specificity, links, authority); a sibling that already ranks near the top is something to protect rather than rewrite.++Check the basics for any page you might name: status, canonical (the URL the page declares as its preferred version), index directives, and how visitors reach it internally. Broaden when a family is missing from the crawl, when siblings perform very differently, when a tool or template page turns out to rank, or when a live query returns a different page than expected.++Run the live checks now, not after drafting: the query cluster each candidate page serves (the head term plus the variants buyers actually use), including both sides of any stronger-versus-weaker comparison. Re-run the queries that decide the leading recommendation before writing. If two checks disagree, write the later one and the earlier in brackets, for example "#10, page 1 (first check: not in the first 20 results)"; that spread is same-day variation, not a trend. One snapshot is not a baseline.++### 3. Shortlist before you decide++Write `opportunities.md` in your working folder (working notes, not the deliverable): one row per serious candidate, usually five to ten, drawn from at least three different kinds of opportunity:-`h1`: the domain. Then one or two opening sentences: the overall state and the one thing.+- an existing page underperforming the demand it targets+- real demand with no page that answers it, including feature, framework, or use-case queries taken from the product's own claims+- a winning page to protect or correct+- an access, indexing, or redirect defect that is costing visits+- helping existing visitors take the next step-If a report template applies (see `seo-report`), its sections and tone replace this list.+Columns: pages | problem observed | evidence (query cluster with US monthly volumes, spot and page or "not in the first 20 results", date) | proposed change | who searches and why they matter to this business | plausible benefit | effort | main uncertainty.-Sections in this order:+If a row's ranking would change with one more lookup (a missing volume, an unchecked sibling, a query you never ran live), do that lookup before ranking.-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.+### 4. Choose++Prefer a bounded change that directly fixes a demonstrated problem for searchers likely to become customers, with a credible path to a meaningful gain. A larger raw-volume opportunity with a weaker diagnosis does not automatically outrank it. A genuine access or indexing blocker, a measurable traffic loss, or a dead domain jumps the queue.++None of these decides on its own: the volume of one sampled query; how easy the fix is; a crawler warning; a hypothetical position-one traffic figure; a navigation or redirect repair with no demonstrated traffic loss. Those belong in the checked table, not the top three. Do not recommend rewriting a page that already ranks near the top for its target query.++Every shortlist row ends in one of two places: a recommendation, or a row in the report's "What else we checked" table with a real reason. "Later, if sales asks for it" is not a reason; "demand is a quarter of the leading candidate's and the page already ranks seventh" is. For the runner-up, write one sentence on why the leader beats it; that sentence goes in the report.++### 5. Size the benefit honestly++- Name the mechanism: a new ranking, a higher position on an existing ranking, or more clicks at the current position. A page that already ranks already receives part of the volume, so a scenario on total volume overstates the gain.+- Size against the cluster the change serves, not one exact term; note overlap instead of adding variants as if they were different people.+- Demand figures are US unless stated; never multiply into an invented global number.+- Search volume is not visits. Use a stated click-share assumption and show it in a scenario table; a position-one scenario is allowed when labeled hypothetical, not promised.+- If the current traffic baseline is unknown, call the figure total potential visits, not additional visits. Do not add overlapping queries.+- Business relevance can be inferred from intent and product fit; say so and label it. Never invent a conversion rate or revenue.+- When there is no number, give a directional assessment and its reason ("already third for its main query, so headroom is small").++### 6. Review, then write++Draft the report body (markdown or HTML, not yet saved). Give the reviewer (a second agent or model if your environment can run one, otherwise a fresh self-review) that draft and the shortlist. The reviewer must: argue the case for the strongest rejected row and say whether the draft answers it; confirm the leading recommendation's evidence is in the draft; confirm every material diagnosis from step 2 survived as a recommendation or a table row; check dates, geography, and rank conventions; and flag paragraph-length bullets and jargon. Fix what it finds, verify any new factual claim against the evidence, then write and save through `seo-report`.++## Output format-Use a note for anything you could not verify or where the site's goal makes a standard recommendation the wrong call.+Use the title conventions in `seo-report`. Sections, in order:++1. **Your next SEO move**: two or three bullets. First action, next action if any, and what is already working. These bullets replace the starter template's opening paragraph and its closing "What to do next" section; include neither.+2. **Recommendations**: one to three, in priority order. Each is an `h3` naming the action and the page or small group, then:+ - **Do this**: two to four bullets. Start with a verb, name what changes, link the page.+ - **Why**: two to four bullets. The observed gap, who searches and why they matter, the plausible benefit, the main uncertainty. Benefit and confidence stay together.+ - A small evidence table (demand and current visibility, or stronger-versus-weaker sibling, or observed content versus proposed). Make the table explain itself: put geography and date in the column header, write positions as "#10 (page 1)" or "not in the first 20 results" (never "10/17", arrows, or listing counts), and say "estimated" in the volume header. Add a "How to read this" bullet only for a limit the headers cannot carry. Optionally a two-row scenario table labeled hypothetical.+3. **What else we checked**: one table: Opportunity | What we found | Decision. One row per shortlist row that did not become a recommendation, starting with the runner-up and its sentence from step 4, plus one row grouping maintenance. Keep cells to a line.+4. **How this report was made**: the fixed skill link line from `seo-report` (URL `https://openseo.so/docs/skills/seo-audit`, text "OpenSEO SEO Audit skill"), a two-line coverage and limits note, then a `<details><summary>Evidence and methodology</summary>` block, closed by default, holding the crawl sample, page families read, the full live-check table (query, volume, position, organic listings returned, time), calculations, and sources. Keep it self-contained; local file paths are not evidence.++Writing rules: short bullets, one idea each, usually 8–20 words. No Problem / Change / Expected effect paragraphs and no repeated summaries. There is no word target; if the main body outgrows about two screens, move supporting detail into the disclosure instead of deleting it. If the research establishes no worthwhile action, say what is working and what the audit could not establish rather than filling the format.++Skeleton for one recommendation and the checked table (keep the `seo-report` CSS unchanged; every `h2` needs an id and a contents-rail entry):++```html+<h2 id="recommendations">Recommendations</h2>+<h3>Make the Northwind comparison answer a switching decision</h3>+<p><strong>Do this</strong></p>+<ul>+ <li>Replace the shared table on <a href="URL" target="_blank" rel="noopener">/northwind-alternative</a> with Northwind-specific tradeoffs.</li>+ <li>Add a sourced migration section: policies, evidence, audit continuity.</li>+</ul>+<p><strong>Why</strong></p>+<ul>+ <li>Same comparison text as two siblings; only the vendor name changes.</li>+ <li>Searchers are already evaluating a switch, the closest fit to a demo.</li>+ <li>Position-one scenario: about 40–60 total US visits a month. Hypothetical, not a forecast.</li>+</ul>+<div class="tw"><table>+ <thead><tr><th>Query</th><th class="n">Est. US searches/mo</th><th>Acme position, US, Sep 18, 2026</th></tr></thead>+ <tbody><tr><td>northwind alternative</td><td class="n">50</td><td>#9 (page 1)</td></tr></tbody>+</table></div>++<h2 id="what-else-we-checked">What else we checked</h2>+<div class="tw"><table>+ <thead><tr><th>Opportunity</th><th>What we found</th><th>Decision</th></tr></thead>+ <tbody><tr><td>Software buying guide</td><td>390 est. US searches/mo; not in the first 20 results; page explains criteria, compares no vendors</td><td>Runner-up. Larger demand, but a weaker diagnosis and a full rewrite; test the comparison page first.</td></tr></tbody>+</table></div>+```## 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.+- Calm, plain tone. No exclamation points, drama words, or filler; no em dashes in prose (the report title convention in `seo-report` is the exception). Severity words only where literally true.+- Gloss each term of art in plain English on first use: canonical, meta description, crawler, 301, structured data.+- Observations are not causes. Similar content plus uneven rankings, a crawler warning, or missing provider rows never prove a penalty, an indexing exclusion, or the reason a page ranks where it does.+- Retrieval date is not observation date. Say when a ranking was observed, or say unknown.+- Missing backlink or ranking data means "no recorded data", not a problem.+- Treat difficulty and volume as inputs, not goals. A small query can matter to a high-value business; an easy one is not automatically worthwhile.+- Separate what the tools reported from what you verified yourself, and say both in the closing section.diff --git a/.agents/skills/seo-coach/SKILL.md b/.agents/skills/seo-coach/SKILL.mdindex 2943b8b0..1ea5f698 100644--- a/.agents/skills/seo-coach/SKILL.md+++ b/.agents/skills/seo-coach/SKILL.md@@ -61,7 +61,7 @@ Coach mode is on. Which project are we working on, and are you new to SEO or expGood starting points once I know the project:- Read what the project already knows (free)-- Audit the site and find the one thing to do this week+- Audit the site and find improvements worth making- Pull Search Console to see what already ranks (free)- Find keyword opportunities from a few seed topics```@@ -85,7 +85,7 @@ Want to go deeper?## What each workflow does- `seo-project-setup`: verifies MCP, interviews the user about scope, goals, positioning, competitors, and key pages, and saves it all to the project's shared context. Also 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.+- `seo-audit`: audits a site and explains material SEO problems, worthwhile improvements, and their likely effects on traffic and the business. A useful starting point when you have an existing site and want to understand what is worth improving.- `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.diff --git a/.agents/skills/seo-report/SKILL.md b/.agents/skills/seo-report/SKILL.mdindex 7dfbe1a9..a624ca2d 100644--- a/.agents/skills/seo-report/SKILL.md+++ b/.agents/skills/seo-report/SKILL.md@@ -9,7 +9,7 @@ description: "Write and save an OpenSEO report as one self-contained HTML page.Turn finished research into one self-contained HTML page, saved to the project with `save_report`, so anyone on the team can open it in the app, read it on a phone, and print it to PDF.-Every OpenSEO skill that produces a recommendation delivers through this skill. Chat gets the link, the verdict, and the top action. The report gets everything else.+Every OpenSEO skill that produces a recommendation delivers through this skill. Chat gets the link, the verdict, and the leading recommendation with its expected benefit, if there is one. The report gets everything else.## Before you write@@ -25,11 +25,13 @@ Use a template only when the user names it, or asks for the kind of report a tem## Writing rules-- **Write notes, not essays.** The reader scans. A finding is a heading and two or three short bullets: Status (what is true, with the number), Fix (the step), and Why only when it is not obvious. No paragraph runs past two sentences. A section opens with one sentence or none. A summary section (a verdict, a snapshot, a market read) is a bullet list, one fact per line, never prose. How the data was gathered goes in the closing "How this report was made" section, not in the finding.-- **Be specific and numeric.** "Position 4.6, one click on 1,085 impressions" beats "underperforming". Every claim carries the number, the quoted tag, or the URL that proves it.+When the producing skill specifies a recommendation format, use that format instead of the generic Problem / Change / Expected effect structure below. For example, an SEO audit can use short Do this / Why bullet lists. Keep the same requirements for concrete actions, supporting evidence, business benefit, and honest uncertainty. The starter template's finding markup is an example, not an override of that skill's format.++- **Write notes, not essays.** The reader scans. A recommendation is a heading and three short bullets: Problem (what is true, with evidence), Change (the step and how it addresses the problem), and Expected effect (what could improve, why the business cares, and the likely scale and uncertainty). For descriptive findings, use the relevant subset; do not invent a fix. No paragraph runs past two sentences. A section opens with one sentence or none. A summary section (a verdict, a snapshot, a market read) is a bullet list, one fact per line, never prose. How the data was gathered goes in the closing "How this report was made" section, not in the finding.+- **Make the reasoning visible.** Use numbers and specific pages to support observations. Explain the mechanism and expected benefit of recommendations in plain language; do not omit that explanation for brevity or replace it with generic claims such as "builds trust." Distinguish measured outcomes, estimates, and hypotheses. A supported qualitative assessment is better than invented precision.- **Be honest about confidence.** Say which numbers came from a tool and which you verified yourself. When you could not check something, put it in a `.note` and say so.- **Plain language.** Gloss every term of art on first use: canonical, meta description, crawler, 301, structured data. No drama words, no exclamation points, no filler.-- **One report, one spine.** Lead with the verdict, then the single most important action, then the supporting detail. A report with twenty findings has failed.+- **One report, one spine.** Lead with the verdict and its business implication, then the material findings and worthwhile recommendations. If the research does not establish a worthwhile action, state that conclusion and the relevant limits. A report with twenty findings has failed.- **Print the numbers.** A chart never carries a value that is not also written out in text.## Title and summary@@ -37,11 +39,11 @@ Use a template only when the user names it, or asks for the kind of report a tem- `title`: names the report type or specific subject and the full report date, under 120 characters. Use "Competitive Landscape — Sep 17, 2026" or "Keyword Research — Sep 17, 2026". Use the actual report date in `MMM D, YYYY` format, including the day and four-digit year; put the data coverage period in the report body. Never a generic "SEO Report" or "Analysis".- Omit the website from the title when the report is about the project's website. Compare hostnames, ignoring the protocol, `www.`, and trailing slash. If the subject is a different website, include its bare hostname, for example "Competitor Analysis: example.com — Sep 17, 2026". Also include the subject hostname when the project has no website set. Never put `https://` or a full URL in the title.- Use the same title in `save_report`, the HTML `<title>`, and the visible `<h1>` so the report list, share preview, and report agree.-- `summary`: markdown under 2,500 characters, in this order — the verdict, the single top action, then the key numbers. This is what `list_reports` returns and what you or another agent read instead of the HTML, so write it for a reader who will never open the page.+- `summary`: markdown under 2,500 characters, in this order — the verdict, the leading recommendation and expected benefit (or why no material action is established), then the key evidence. This is what `list_reports` returns and what you or another agent read instead of the HTML, so write it for a reader who will never open the page.## The closing section: how this report was made-Every report ends with an `h2` titled "How this report was made" (id `how-this-report-was-made`), after "What to do next". It is the only section with a fixed opening line: one sentence naming the skill that produced the report and linking its docs page, so a reader who was handed the link can learn what the workflow does and rerun it.+Every report ends with an `h2` titled "How this report was made" (id `how-this-report-was-made`). When "What to do next" is included, place it immediately before this section. It is the only section with a fixed opening line: one sentence naming the skill that produced the report and linking its docs page, so a reader who was handed the link can learn what the workflow does and rerun it.```html<p>Generated by the <a href="https://openseo.so/docs/skills/seo-audit" target="_blank" rel="noopener">OpenSEO SEO Audit skill</a>, run by AGENT NAME on MONTH D, YYYY.</p>@@ -64,7 +66,7 @@ These are enforced by the viewer, not by taste. A report that breaks them render## After you save-- `save_report` returns `{ reportId, url, htmlBytes }`. The whole reply is at most three short bullets, then the link last on its own line as `Read the full report: <url>`. The bullets: the verdict, the top action, and anything the user has to act on (a project you created, a question you need answered). Nothing else: no account of the run, no reviewer notes, no list of what worked, no restating the report. The report is how they learn; chat only points at it.+- `save_report` returns `{ reportId, url, htmlBytes }`. The whole reply is at most three short bullets, then the link last on its own line as `Read the full report: <url>`. The bullets: the verdict, the leading recommendation and expected benefit if supported, and anything the user has to act on (a project you created, a question you need answered). Nothing else: no account of the run, no reviewer notes, no list of what worked, no restating the report. The report is how they learn; chat only points at it.- The skill you are running appends its own research-log line; add one only if it does not: `{ appendResearchLog: { summary: "Report: <title>. Verdict: <conclusion>" } }`.- If the save fails, the error names the limit and the value. Fix that one thing and save again. Never paste the report into chat instead.@@ -184,14 +186,15 @@ footer{max-width:660px;margin:64px 0 0;padding:26px 0 0;border-top:1px solid var</div></aside><article>- <p>One or two sentences: the state of things and the one action.</p>+ <p>One or two sentences: the state of things and what it means for the business.</p><h2 id="section-heading">SECTION HEADING</h2><h3>FINDING TITLE</h3><ul class="finding">- <li><b>Status:</b> what is true, with the number or the quoted tag that proves it.</li>- <li><b>Fix:</b> the concrete step, doable this week by a non-technical person.</li>+ <li><b>Problem:</b> the observed gap, with the evidence and affected page.</li>+ <li><b>Change:</b> the concrete step and how it addresses the gap.</li>+ <li><b>Expected effect:</b> what could improve, why the business cares, and the likely scale and uncertainty.</li></ul><div class="note"><p>A caveat, a confidence note, or something you could not verify.</p></div>@@ -213,7 +216,7 @@ footer{max-width:660px;margin:64px 0 0;padding:26px 0 0;border-top:1px solid var<hr><h2 id="what-to-do-next">What to do next</h2>- <ol><li>The top priority, first.</li></ol>+ <ol><li>The first step for worthwhile work and how to check the intended result. Omit if no action is supported.</li></ol><h2 id="how-this-report-was-made">How this report was made</h2><p>Generated by the <a href="https://openseo.so/docs/skills/SKILL-NAME" target="_blank" rel="noopener">OpenSEO SKILL TITLE skill</a>, run by AGENT NAME on MONTH D, YYYY.</p>@@ -234,7 +237,7 @@ footer{max-width:660px;margin:64px 0 0;padding:26px 0 0;border-top:1px solid var- **Header** — `h1` (the report title) and `.byline` (who it is for and the date): "Prepared for badseo.dev · September 3, 2026".- **`.rail` contents** — the table of contents, sticky to the right of the text on a wide screen, dropped on a phone and in print. Every `h2` has an id, and the contents list links to each one with a plain `href="#id"` — in-page anchors are the one kind of link that must **not** use `target="_blank"`. Ids are the kebab-case of the heading text.- **`h2` / `h3`** — `h2` opens a section, `h3` names one finding. Do not skip levels.-- **Finding** — `h3`, then a `.finding` list: `<li><b>Status:</b> …</li>`, `<li><b>Fix:</b> …</li>`, and `<li><b>Why:</b> …</li>` only when the reason is not obvious. Each bullet is one or two sentences. This is the workhorse; most of a report is a run of these.+- **Finding** — use the producing skill's recommendation structure when specified; otherwise `h3`, then a `.finding` list with Problem, Change, and Expected effect, each one or two sentences. Keep the expected benefit visible beside the proposed work, including when it is uncertain or limited. Descriptive findings can use only the relevant bullets.- **`.note`** — one left-ruled callout for a caveat, a confidence limit, or something you could not verify. Two or three in a report, never a row of them.- **`.tw` table** — every numeric column gets `class="n"` on both the `th` and the `td` so the digits line up. Keep tables to five columns or fewer, put the long-text column last, and keep cell text short; a wide table scrolls on a phone and clips in print.- **`figure` + `.bars`** — one small bar chart where a comparison reads faster than a sentence. One row per item: `.label`, a `.track` holding a `.bar` whose inline width is the value as a percentage of the largest, and `.value`. Inline SVG is fine for anything that is not a bar chart; give it a `viewBox` and real `<text>` labels.diff --git a/.claude/skills/evaluate-skill b/.claude/skills/evaluate-skillnew file mode 120000index 00000000..09b1fd2f--- /dev/null+++ b/.claude/skills/evaluate-skill@@ -0,0 +1 @@+../../.agents/skills/evaluate-skill\ No newline at end of filediff --git a/knip.jsonc b/knip.jsoncindex ddb70978..8ba3cae6 100644--- a/knip.jsonc+++ b/knip.jsonc@@ -32,6 +32,9 @@// Alchemy state/bundle artifacts (gitignored)"!.alchemy/**","!badseo/**",+ // Skill-bundled scripts, run by hand from the skill's instructions+ "!.agents/**",+ "!.claude/**",],"ignore": ["drizzle-prod.config.ts"],// Disable Drizzle plugin - it tries to load drizzle.config.ts which imports cloudflare:workersdiff --git a/plugins/openseo/skills/seo-audit/SKILL.md b/plugins/openseo/skills/seo-audit/SKILL.mdindex 1a41c92d..eb1cb0e4 100644--- a/plugins/openseo/skills/seo-audit/SKILL.md+++ b/plugins/openseo/skills/seo-audit/SKILL.md@@ -1,84 +1,140 @@---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."+description: "Audit a website, investigate its real search opportunities, and deliver a short data-backed report on the few changes most likely to grow organic traffic that converts."---# 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.+Find the work that would most improve a site's useful organic traffic, then explain it so a non-expert can act on it. Research broadly; recommend selectively. The report leads with one to three recommendations that either capture meaningfully more qualified search demand or stop a real loss.-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.+Use this when asked for an SEO audit or review of a domain, especially for a shareable report. For expert-facing analysis of a competitor or market, use `competitor-analysis` or `competitive-landscape` instead.-## Required inputs+## Inputs and project context-- Domain to audit-- `projectId` (use `list_projects`; if no project matches the domain, create one with `create_project`)+- Domain to audit and `projectId` (`list_projects`; if no project matches, `create_project`).+- Call `get_project_context` first. This skill needs `business_overview`. If it is empty, infer what the business does from the site, confirm it with the user in one question, write it back with `update_project_context`, and continue. Suggest `seo-project-setup` at the end for the rest; never front-load the full interview.+- Reuse research-log results under 30 days old for discovery. A ranking claim that drives a recommendation still needs a live check made during this audit.+- On finish, write back what is durable with `update_project_context` (a corrected `business_overview`, the pages the report names via `addKeyPages`) and append `{ appendResearchLog: { summary: "Site audit: <domain>. Verdict: <conclusion>" } }`.-## Project context+Deliver through the `seo-report` skill, saving with `skill: "seo-audit"`. If that skill is unavailable, say so and stop before writing HTML.-The project-context tools are free and shared with the app and other agents.+## OpenSEO MCP tools-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>" } }`.+- `whoami`: confirm the connection and credits before spending. If OpenSEO is not connected, stop and ask the user to connect it.+- `run_site_audit`, then `get_audit_status` (wait a minute or two between checks), `get_audit_issues`, `get_audit_pages`. Leave Lighthouse off unless the user asked for performance depth. Crawl reads are free.+- `get_backlinks_overview` and `get_domain_overview`: orientation only. Provider traffic and keyword counts are estimates with no single observation date; they are not measured visits.+- `get_ranked_keywords`: which queries send which pages traffic. Start with one domain-level call with `resultTypes: ["organic"]`; use `scope: "exact_url"` for the specific pages you compare. A page missing from a limited domain sample is not proof it has no rankings. Ranking rows carry their own `last_updated_time`; keyword metric dates are not ranking dates.+- `get_serp_results`: the live check behind every ranking claim in the report. The returned `rank` counts every result block, so count organic (unpaid) listings yourself and report the spot with its page, ten spots per page: "#10 (page 1)", "#11 (page 2)". Request depth 20; a page not seen is "not in the first 20 results". Record the exact query, country, language, date, how many organic listings came back, and the matching URL; those details go in the evidence appendix, not the tables. A failed lookup is unknown, not "not in the first 20 results".+- `get_search_console_performance`: when connected, first-party clicks and impressions separate low visibility from low click-through. Missing access is a coverage gap, not a blocker.+- `get_keyword_metrics` and `research_keywords`: demand for the queries a candidate page targets. One focused metrics batch usually suffices; one research call with 1–3 seeds when a demand gap could change the decision.+- Web reading (fetch, scrape, or search): the site's own pages, sitemap, the leading results for a query, and competitor pages.-## Deliver as a report+Research until another lookup is unlikely to change which opportunities lead. Respect an explicit user budget and say which comparison it prevented.-Deliver through the `seo-report` skill, saving with `skill: "seo-audit"`. If that skill is not available, say so and stop before writing HTML.+## Workflow-## OpenSEO MCP tools+### 1. Orient-- `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.+`whoami`, resolve the project, start `run_site_audit`. While it crawls: backlinks overview, domain overview, the domain-level ranked-keyword sample, and the sitemap plus navigation. Write down the site's page families from the sitemap, not just the crawl sample: product, pricing, comparison or alternative, tools and templates, guides, categories, services, locations, whatever the site actually has.-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.+If the crawl is broken or nearly empty (certificate error, 5xx, one page), investigate before anything else. Check redirects and certificate variants yourself and search for the business; a dead domain with a live successor flips the whole recommendation to "redirect the old domain".-## Workflow+### 2. Investigate every family that matters to the goal-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).+For each family that could bring buyers, read at least two pages' main content (ignore navigation and shared templates): the page performing best in the ranking data and one performing worst or typical. For each page ask: what decision or question does its searcher have, and does the page answer it with specific, accurate, sourced information, or does it substitute a name, location, or keyword into a shared answer? Compare against what the leading results for that query provide.-## Output format+A common SaaS pattern worth checking directly: competitor comparison or alternative pages and competitor pricing pages are two separate families, each answering a different buying question. Read siblings side by side. Investigate uneven visibility between siblings (intent, content specificity, links, authority); a sibling that already ranks near the top is something to protect rather than rewrite.++Check the basics for any page you might name: status, canonical (the URL the page declares as its preferred version), index directives, and how visitors reach it internally. Broaden when a family is missing from the crawl, when siblings perform very differently, when a tool or template page turns out to rank, or when a live query returns a different page than expected.++Run the live checks now, not after drafting: the query cluster each candidate page serves (the head term plus the variants buyers actually use), including both sides of any stronger-versus-weaker comparison. Re-run the queries that decide the leading recommendation before writing. If two checks disagree, write the later one and the earlier in brackets, for example "#10, page 1 (first check: not in the first 20 results)"; that spread is same-day variation, not a trend. One snapshot is not a baseline.++### 3. Shortlist before you decide++Write `opportunities.md` in your working folder (working notes, not the deliverable): one row per serious candidate, usually five to ten, drawn from at least three different kinds of opportunity:-`h1`: the domain. Then one or two opening sentences: the overall state and the one thing.+- an existing page underperforming the demand it targets+- real demand with no page that answers it, including feature, framework, or use-case queries taken from the product's own claims+- a winning page to protect or correct+- an access, indexing, or redirect defect that is costing visits+- helping existing visitors take the next step-If a report template applies (see `seo-report`), its sections and tone replace this list.+Columns: pages | problem observed | evidence (query cluster with US monthly volumes, spot and page or "not in the first 20 results", date) | proposed change | who searches and why they matter to this business | plausible benefit | effort | main uncertainty.-Sections in this order:+If a row's ranking would change with one more lookup (a missing volume, an unchecked sibling, a query you never ran live), do that lookup before ranking.-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.+### 4. Choose++Prefer a bounded change that directly fixes a demonstrated problem for searchers likely to become customers, with a credible path to a meaningful gain. A larger raw-volume opportunity with a weaker diagnosis does not automatically outrank it. A genuine access or indexing blocker, a measurable traffic loss, or a dead domain jumps the queue.++None of these decides on its own: the volume of one sampled query; how easy the fix is; a crawler warning; a hypothetical position-one traffic figure; a navigation or redirect repair with no demonstrated traffic loss. Those belong in the checked table, not the top three. Do not recommend rewriting a page that already ranks near the top for its target query.++Every shortlist row ends in one of two places: a recommendation, or a row in the report's "What else we checked" table with a real reason. "Later, if sales asks for it" is not a reason; "demand is a quarter of the leading candidate's and the page already ranks seventh" is. For the runner-up, write one sentence on why the leader beats it; that sentence goes in the report.++### 5. Size the benefit honestly++- Name the mechanism: a new ranking, a higher position on an existing ranking, or more clicks at the current position. A page that already ranks already receives part of the volume, so a scenario on total volume overstates the gain.+- Size against the cluster the change serves, not one exact term; note overlap instead of adding variants as if they were different people.+- Demand figures are US unless stated; never multiply into an invented global number.+- Search volume is not visits. Use a stated click-share assumption and show it in a scenario table; a position-one scenario is allowed when labeled hypothetical, not promised.+- If the current traffic baseline is unknown, call the figure total potential visits, not additional visits. Do not add overlapping queries.+- Business relevance can be inferred from intent and product fit; say so and label it. Never invent a conversion rate or revenue.+- When there is no number, give a directional assessment and its reason ("already third for its main query, so headroom is small").++### 6. Review, then write++Draft the report body (markdown or HTML, not yet saved). Give the reviewer (a second agent or model if your environment can run one, otherwise a fresh self-review) that draft and the shortlist. The reviewer must: argue the case for the strongest rejected row and say whether the draft answers it; confirm the leading recommendation's evidence is in the draft; confirm every material diagnosis from step 2 survived as a recommendation or a table row; check dates, geography, and rank conventions; and flag paragraph-length bullets and jargon. Fix what it finds, verify any new factual claim against the evidence, then write and save through `seo-report`.++## Output format-Use a note for anything you could not verify or where the site's goal makes a standard recommendation the wrong call.+Use the title conventions in `seo-report`. Sections, in order:++1. **Your next SEO move**: two or three bullets. First action, next action if any, and what is already working. These bullets replace the starter template's opening paragraph and its closing "What to do next" section; include neither.+2. **Recommendations**: one to three, in priority order. Each is an `h3` naming the action and the page or small group, then:+ - **Do this**: two to four bullets. Start with a verb, name what changes, link the page.+ - **Why**: two to four bullets. The observed gap, who searches and why they matter, the plausible benefit, the main uncertainty. Benefit and confidence stay together.+ - A small evidence table (demand and current visibility, or stronger-versus-weaker sibling, or observed content versus proposed). Make the table explain itself: put geography and date in the column header, write positions as "#10 (page 1)" or "not in the first 20 results" (never "10/17", arrows, or listing counts), and say "estimated" in the volume header. Add a "How to read this" bullet only for a limit the headers cannot carry. Optionally a two-row scenario table labeled hypothetical.+3. **What else we checked**: one table: Opportunity | What we found | Decision. One row per shortlist row that did not become a recommendation, starting with the runner-up and its sentence from step 4, plus one row grouping maintenance. Keep cells to a line.+4. **How this report was made**: the fixed skill link line from `seo-report` (URL `https://openseo.so/docs/skills/seo-audit`, text "OpenSEO SEO Audit skill"), a two-line coverage and limits note, then a `<details><summary>Evidence and methodology</summary>` block, closed by default, holding the crawl sample, page families read, the full live-check table (query, volume, position, organic listings returned, time), calculations, and sources. Keep it self-contained; local file paths are not evidence.++Writing rules: short bullets, one idea each, usually 8–20 words. No Problem / Change / Expected effect paragraphs and no repeated summaries. There is no word target; if the main body outgrows about two screens, move supporting detail into the disclosure instead of deleting it. If the research establishes no worthwhile action, say what is working and what the audit could not establish rather than filling the format.++Skeleton for one recommendation and the checked table (keep the `seo-report` CSS unchanged; every `h2` needs an id and a contents-rail entry):++```html+<h2 id="recommendations">Recommendations</h2>+<h3>Make the Northwind comparison answer a switching decision</h3>+<p><strong>Do this</strong></p>+<ul>+ <li>Replace the shared table on <a href="URL" target="_blank" rel="noopener">/northwind-alternative</a> with Northwind-specific tradeoffs.</li>+ <li>Add a sourced migration section: policies, evidence, audit continuity.</li>+</ul>+<p><strong>Why</strong></p>+<ul>+ <li>Same comparison text as two siblings; only the vendor name changes.</li>+ <li>Searchers are already evaluating a switch, the closest fit to a demo.</li>+ <li>Position-one scenario: about 40–60 total US visits a month. Hypothetical, not a forecast.</li>+</ul>+<div class="tw"><table>+ <thead><tr><th>Query</th><th class="n">Est. US searches/mo</th><th>Acme position, US, Sep 18, 2026</th></tr></thead>+ <tbody><tr><td>northwind alternative</td><td class="n">50</td><td>#9 (page 1)</td></tr></tbody>+</table></div>++<h2 id="what-else-we-checked">What else we checked</h2>+<div class="tw"><table>+ <thead><tr><th>Opportunity</th><th>What we found</th><th>Decision</th></tr></thead>+ <tbody><tr><td>Software buying guide</td><td>390 est. US searches/mo; not in the first 20 results; page explains criteria, compares no vendors</td><td>Runner-up. Larger demand, but a weaker diagnosis and a full rewrite; test the comparison page first.</td></tr></tbody>+</table></div>+```## 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.+- Calm, plain tone. No exclamation points, drama words, or filler; no em dashes in prose (the report title convention in `seo-report` is the exception). Severity words only where literally true.+- Gloss each term of art in plain English on first use: canonical, meta description, crawler, 301, structured data.+- Observations are not causes. Similar content plus uneven rankings, a crawler warning, or missing provider rows never prove a penalty, an indexing exclusion, or the reason a page ranks where it does.+- Retrieval date is not observation date. Say when a ranking was observed, or say unknown.+- Missing backlink or ranking data means "no recorded data", not a problem.+- Treat difficulty and volume as inputs, not goals. A small query can matter to a high-value business; an easy one is not automatically worthwhile.+- Separate what the tools reported from what you verified yourself, and say both in the closing section.diff --git a/plugins/openseo/skills/seo-coach/SKILL.md b/plugins/openseo/skills/seo-coach/SKILL.mdindex 2943b8b0..1ea5f698 100644--- a/plugins/openseo/skills/seo-coach/SKILL.md+++ b/plugins/openseo/skills/seo-coach/SKILL.md@@ -61,7 +61,7 @@ Coach mode is on. Which project are we working on, and are you new to SEO or expGood starting points once I know the project:- Read what the project already knows (free)-- Audit the site and find the one thing to do this week+- Audit the site and find improvements worth making- Pull Search Console to see what already ranks (free)- Find keyword opportunities from a few seed topics```@@ -85,7 +85,7 @@ Want to go deeper?## What each workflow does- `seo-project-setup`: verifies MCP, interviews the user about scope, goals, positioning, competitors, and key pages, and saves it all to the project's shared context. Also 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.+- `seo-audit`: audits a site and explains material SEO problems, worthwhile improvements, and their likely effects on traffic and the business. A useful starting point when you have an existing site and want to understand what is worth improving.- `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.diff --git a/plugins/openseo/skills/seo-report/SKILL.md b/plugins/openseo/skills/seo-report/SKILL.mdindex 7dfbe1a9..a624ca2d 100644--- a/plugins/openseo/skills/seo-report/SKILL.md+++ b/plugins/openseo/skills/seo-report/SKILL.md@@ -9,7 +9,7 @@ description: "Write and save an OpenSEO report as one self-contained HTML page.Turn finished research into one self-contained HTML page, saved to the project with `save_report`, so anyone on the team can open it in the app, read it on a phone, and print it to PDF.-Every OpenSEO skill that produces a recommendation delivers through this skill. Chat gets the link, the verdict, and the top action. The report gets everything else.+Every OpenSEO skill that produces a recommendation delivers through this skill. Chat gets the link, the verdict, and the leading recommendation with its expected benefit, if there is one. The report gets everything else.## Before you write@@ -25,11 +25,13 @@ Use a template only when the user names it, or asks for the kind of report a tem## Writing rules-- **Write notes, not essays.** The reader scans. A finding is a heading and two or three short bullets: Status (what is true, with the number), Fix (the step), and Why only when it is not obvious. No paragraph runs past two sentences. A section opens with one sentence or none. A summary section (a verdict, a snapshot, a market read) is a bullet list, one fact per line, never prose. How the data was gathered goes in the closing "How this report was made" section, not in the finding.-- **Be specific and numeric.** "Position 4.6, one click on 1,085 impressions" beats "underperforming". Every claim carries the number, the quoted tag, or the URL that proves it.+When the producing skill specifies a recommendation format, use that format instead of the generic Problem / Change / Expected effect structure below. For example, an SEO audit can use short Do this / Why bullet lists. Keep the same requirements for concrete actions, supporting evidence, business benefit, and honest uncertainty. The starter template's finding markup is an example, not an override of that skill's format.++- **Write notes, not essays.** The reader scans. A recommendation is a heading and three short bullets: Problem (what is true, with evidence), Change (the step and how it addresses the problem), and Expected effect (what could improve, why the business cares, and the likely scale and uncertainty). For descriptive findings, use the relevant subset; do not invent a fix. No paragraph runs past two sentences. A section opens with one sentence or none. A summary section (a verdict, a snapshot, a market read) is a bullet list, one fact per line, never prose. How the data was gathered goes in the closing "How this report was made" section, not in the finding.+- **Make the reasoning visible.** Use numbers and specific pages to support observations. Explain the mechanism and expected benefit of recommendations in plain language; do not omit that explanation for brevity or replace it with generic claims such as "builds trust." Distinguish measured outcomes, estimates, and hypotheses. A supported qualitative assessment is better than invented precision.- **Be honest about confidence.** Say which numbers came from a tool and which you verified yourself. When you could not check something, put it in a `.note` and say so.- **Plain language.** Gloss every term of art on first use: canonical, meta description, crawler, 301, structured data. No drama words, no exclamation points, no filler.-- **One report, one spine.** Lead with the verdict, then the single most important action, then the supporting detail. A report with twenty findings has failed.+- **One report, one spine.** Lead with the verdict and its business implication, then the material findings and worthwhile recommendations. If the research does not establish a worthwhile action, state that conclusion and the relevant limits. A report with twenty findings has failed.- **Print the numbers.** A chart never carries a value that is not also written out in text.## Title and summary@@ -37,11 +39,11 @@ Use a template only when the user names it, or asks for the kind of report a tem- `title`: names the report type or specific subject and the full report date, under 120 characters. Use "Competitive Landscape — Sep 17, 2026" or "Keyword Research — Sep 17, 2026". Use the actual report date in `MMM D, YYYY` format, including the day and four-digit year; put the data coverage period in the report body. Never a generic "SEO Report" or "Analysis".- Omit the website from the title when the report is about the project's website. Compare hostnames, ignoring the protocol, `www.`, and trailing slash. If the subject is a different website, include its bare hostname, for example "Competitor Analysis: example.com — Sep 17, 2026". Also include the subject hostname when the project has no website set. Never put `https://` or a full URL in the title.- Use the same title in `save_report`, the HTML `<title>`, and the visible `<h1>` so the report list, share preview, and report agree.-- `summary`: markdown under 2,500 characters, in this order — the verdict, the single top action, then the key numbers. This is what `list_reports` returns and what you or another agent read instead of the HTML, so write it for a reader who will never open the page.+- `summary`: markdown under 2,500 characters, in this order — the verdict, the leading recommendation and expected benefit (or why no material action is established), then the key evidence. This is what `list_reports` returns and what you or another agent read instead of the HTML, so write it for a reader who will never open the page.## The closing section: how this report was made-Every report ends with an `h2` titled "How this report was made" (id `how-this-report-was-made`), after "What to do next". It is the only section with a fixed opening line: one sentence naming the skill that produced the report and linking its docs page, so a reader who was handed the link can learn what the workflow does and rerun it.+Every report ends with an `h2` titled "How this report was made" (id `how-this-report-was-made`). When "What to do next" is included, place it immediately before this section. It is the only section with a fixed opening line: one sentence naming the skill that produced the report and linking its docs page, so a reader who was handed the link can learn what the workflow does and rerun it.```html<p>Generated by the <a href="https://openseo.so/docs/skills/seo-audit" target="_blank" rel="noopener">OpenSEO SEO Audit skill</a>, run by AGENT NAME on MONTH D, YYYY.</p>@@ -64,7 +66,7 @@ These are enforced by the viewer, not by taste. A report that breaks them render## After you save-- `save_report` returns `{ reportId, url, htmlBytes }`. The whole reply is at most three short bullets, then the link last on its own line as `Read the full report: <url>`. The bullets: the verdict, the top action, and anything the user has to act on (a project you created, a question you need answered). Nothing else: no account of the run, no reviewer notes, no list of what worked, no restating the report. The report is how they learn; chat only points at it.+- `save_report` returns `{ reportId, url, htmlBytes }`. The whole reply is at most three short bullets, then the link last on its own line as `Read the full report: <url>`. The bullets: the verdict, the leading recommendation and expected benefit if supported, and anything the user has to act on (a project you created, a question you need answered). Nothing else: no account of the run, no reviewer notes, no list of what worked, no restating the report. The report is how they learn; chat only points at it.- The skill you are running appends its own research-log line; add one only if it does not: `{ appendResearchLog: { summary: "Report: <title>. Verdict: <conclusion>" } }`.- If the save fails, the error names the limit and the value. Fix that one thing and save again. Never paste the report into chat instead.@@ -184,14 +186,15 @@ footer{max-width:660px;margin:64px 0 0;padding:26px 0 0;border-top:1px solid var</div></aside><article>- <p>One or two sentences: the state of things and the one action.</p>+ <p>One or two sentences: the state of things and what it means for the business.</p><h2 id="section-heading">SECTION HEADING</h2><h3>FINDING TITLE</h3><ul class="finding">- <li><b>Status:</b> what is true, with the number or the quoted tag that proves it.</li>- <li><b>Fix:</b> the concrete step, doable this week by a non-technical person.</li>+ <li><b>Problem:</b> the observed gap, with the evidence and affected page.</li>+ <li><b>Change:</b> the concrete step and how it addresses the gap.</li>+ <li><b>Expected effect:</b> what could improve, why the business cares, and the likely scale and uncertainty.</li></ul><div class="note"><p>A caveat, a confidence note, or something you could not verify.</p></div>@@ -213,7 +216,7 @@ footer{max-width:660px;margin:64px 0 0;padding:26px 0 0;border-top:1px solid var<hr><h2 id="what-to-do-next">What to do next</h2>- <ol><li>The top priority, first.</li></ol>+ <ol><li>The first step for worthwhile work and how to check the intended result. Omit if no action is supported.</li></ol><h2 id="how-this-report-was-made">How this report was made</h2><p>Generated by the <a href="https://openseo.so/docs/skills/SKILL-NAME" target="_blank" rel="noopener">OpenSEO SKILL TITLE skill</a>, run by AGENT NAME on MONTH D, YYYY.</p>@@ -234,7 +237,7 @@ footer{max-width:660px;margin:64px 0 0;padding:26px 0 0;border-top:1px solid var- **Header** — `h1` (the report title) and `.byline` (who it is for and the date): "Prepared for badseo.dev · September 3, 2026".- **`.rail` contents** — the table of contents, sticky to the right of the text on a wide screen, dropped on a phone and in print. Every `h2` has an id, and the contents list links to each one with a plain `href="#id"` — in-page anchors are the one kind of link that must **not** use `target="_blank"`. Ids are the kebab-case of the heading text.- **`h2` / `h3`** — `h2` opens a section, `h3` names one finding. Do not skip levels.-- **Finding** — `h3`, then a `.finding` list: `<li><b>Status:</b> …</li>`, `<li><b>Fix:</b> …</li>`, and `<li><b>Why:</b> …</li>` only when the reason is not obvious. Each bullet is one or two sentences. This is the workhorse; most of a report is a run of these.+- **Finding** — use the producing skill's recommendation structure when specified; otherwise `h3`, then a `.finding` list with Problem, Change, and Expected effect, each one or two sentences. Keep the expected benefit visible beside the proposed work, including when it is uncertain or limited. Descriptive findings can use only the relevant bullets.- **`.note`** — one left-ruled callout for a caveat, a confidence limit, or something you could not verify. Two or three in a report, never a row of them.- **`.tw` table** — every numeric column gets `class="n"` on both the `th` and the `td` so the digits line up. Keep tables to five columns or fewer, put the long-text column last, and keep cell text short; a wide table scrolls on a phone and clips in print.- **`figure` + `.bars`** — one small bar chart where a comparison reads faster than a sentence. One row per item: `.label`, a `.track` holding a `.bar` whose inline width is the value as a percentage of the largest, and `.value`. Inline SVG is fine for anything that is not a bar chart; give it a `viewBox` and real `<text>` labels.diff --git a/src/routes/_project/p/$projectId/reports/$reportId.tsx b/src/routes/_project/p/$projectId/reports/$reportId.tsxindex 5774034a..51fb0212 100644--- a/src/routes/_project/p/$projectId/reports/$reportId.tsx+++ b/src/routes/_project/p/$projectId/reports/$reportId.tsx@@ -257,41 +257,24 @@ function ReportDetailPage() {{(close) => (<>{hosted ? (- <li>- <button- onClick={() => {- close();- exportPdf();- }}- >- <FileDown className="size-4" />- Export- </button>- </li>+ <>+ <li>+ <button+ onClick={() => {+ close();+ exportPdf();+ }}+ >+ <FileDown className="size-4" />+ Export+ </button>+ </li>+ <li+ role="separator"+ className="mx-1 my-1 h-px bg-base-300"+ />+ </>) : null}- <li>- <button- onClick={() => {- close();- setExpanded(true);- }}- >- <Maximize2 className="size-4" />- Full screen- </button>- </li>- <li>- <a- href={`/r/${report.id}`}- target="_blank"- rel="noreferrer"- onClick={close}- >- <ExternalLink className="size-4" />- Open in new tab- </a>- </li>- <li role="separator" className="mx-1 my-1 h-px bg-base-300" /><li><buttonclassName="text-error"@@ -311,7 +294,33 @@ function ReportDetailPage() {</div></div>- <div className="min-h-0 flex-1">+ <div className="relative min-h-0 flex-1">+ {/* View controls float over the top-right corner of the report frame.+ They belong to the viewer, not the document, so they overlay the+ iframe instead of being injected into it. Placed before the iframe+ so keyboard focus reaches them without tabbing through the report;+ inset from the edge so they clear a classic scrollbar. */}+ <div className="absolute top-1 right-5 flex items-center gap-0.5 rounded-md border border-base-300 bg-base-100/95 p-0.5 shadow-sm backdrop-blur">+ <button+ type="button"+ className="btn btn-ghost btn-sm btn-square"+ aria-label="Full screen"+ title="Full screen"+ onClick={() => setExpanded(true)}+ >+ <Maximize2 className="size-4" />+ </button>+ <a+ href={`/r/${report.id}`}+ target="_blank"+ rel="noreferrer"+ className="btn btn-ghost btn-sm btn-square"+ aria-label="Open in new tab"+ title="Open in new tab"+ >+ <ExternalLink className="size-4" />+ </a>+ </div><ReportViewer src={`/r/${report.id}`} title={report.title} /></div>diff --git a/src/shared/report-sandbox.ts b/src/shared/report-sandbox.tsindex d6ce4bcb..9cbcb120 100644--- a/src/shared/report-sandbox.ts+++ b/src/shared/report-sandbox.ts@@ -34,12 +34,13 @@ export const REPORT_CSP = `sandbox ${REPORT_IFRAME_SANDBOX}; ${CSP_TAIL}`;/*** The script print mode appends, and the only script authorized to run in a- * report. A small delay after `load`, so fonts and images settle before the- * dialog snapshots the page. It is injected with no attributes at all — see- * withPrintScript.+ * report. It opens every closed `<details>` first, so an evidence appendix a+ * skill collapsed on screen still lands in the PDF, then waits a little after+ * `load` so fonts and images settle before the dialog snapshots the page. It is+ * injected with no attributes at all — see withPrintScript.*/export const PRINT_SCRIPT =- 'addEventListener("load",()=>{setTimeout(()=>print(),150)})';+ 'addEventListener("load",()=>{for(const d of document.querySelectorAll("details"))d.open=true;setTimeout(()=>print(),150)})';/*** Base64 SHA-256 of PRINT_SCRIPT, for the `script-src` hash source. Hardcoded@@ -49,7 +50,7 @@ export const PRINT_SCRIPT =* of silently breaking printing.*/export const PRINT_SCRIPT_SHA256 =- "thhppZwgMkIvdqds8iPeCMHMT5bX6Wi4nx2PdnxB36w=";+ "uE0MLbgBgIu3I3pghlY0762kVHKlP7Udz5qzZNT7piw=";/*** The policy for one response. Outside print mode it is REPORT_CSP, byte fordiff --git a/web/content/docs/skills/index.md b/web/content/docs/skills/index.mdindex 92b534f7..0b481a25 100644--- a/web/content/docs/skills/index.md+++ b/web/content/docs/skills/index.md@@ -27,7 +27,7 @@ MCP connects your agent to OpenSEO data. Skills tell your agent which SEO workfl## 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.+- [SEO Audit](/docs/skills/seo-audit): audit a site and understand its important problems, worthwhile improvements, and likely effects on traffic and the business.## Research workflowsdiff --git a/web/content/docs/skills/seo-audit.mdx b/web/content/docs/skills/seo-audit.mdxindex e6358fe0..9cd01169 100644--- a/web/content/docs/skills/seo-audit.mdx+++ b/web/content/docs/skills/seo-audit.mdx@@ -1,23 +1,25 @@---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."+description: "Audit a website with your AI agent and understand its important SEO problems, worthwhile improvements, and likely effects on traffic and the business."---<RunSkillCallout command="/seo-audit" />-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.+The SEO Audit Agent Skill audits a site and writes a concise HTML report that anyone can understand and use, 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.+Your agent checks the site's technical health, important pages, links, and search visibility. It checks ranking assumptions against live search results and weighs the likely benefit of proposed work against the effort. The report explains the problems found, how proposed changes could affect traffic or potential customers, and whether the likely benefit warrants the effort. It separates confirmed findings from hypotheses and says when the audit has not established a substantial improvement worth making.The skill is plain `SKILL.md` instructions, so it runs in Claude Code, Codex, or any agent that supports the skills format. It delivers through the [SEO Report skill](/docs/skills/seo-report): the finished page is saved to your OpenSEO project and appears on the project's Reports page, where anyone on your team can open it or print it to PDF.## 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.+- Crawl the site, read the prioritized issues, and map the page families the crawl missed using the sitemap.+- Check backlinks, traffic estimates, and which pages appear for relevant searches.+- Read stronger and weaker pages in each important family side by side and judge whether each answers its own searcher's question with specific, accurate information.+- Verify ranking assumptions with live search results before choosing a priority.+- Build a shortlist of opportunities across different kinds of work, then choose the few whose likely benefit warrants the effort. An easy fix or a big raw search volume does not win on its own.+- Explain each recommendation with short "Do this" and "Why" bullets, a compact evidence table, and, when useful, a labeled traffic scenario.+- Show everything else it weighed in one "What else we checked" table with a one-line decision, so material findings are never dropped.- Explain every technical term in plain English the first time it appears.- Save the result to your project as a single HTML page anyone on your team can open or print.@@ -25,11 +27,11 @@ The skill is plain `SKILL.md` instructions, so it runs in Claude Code, Codex, orUse 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".+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 or a dead domain with a live successor site each call for a different response.## What you get back-One report on your project's Reports 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. In chat you get the link, the verdict, and the one thing to do.+One report on your project's Reports page. It opens with your next SEO move, then one to three recommendations, each naming a page or small group with "Do this" and "Why" bullets and a small evidence table. A "What else we checked" table lists the other opportunities the audit weighed and why they lost. The full evidence sits in an expandable section at the end. There is no fixed length: the prose stays light, and the data stays visible. In chat you get the link, the verdict, and the leading recommendation.## How to get the best result@@ -37,10 +39,11 @@ One report on your project's Reports page: a three-sentence summary, the single- 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.+- Give the agent a research budget if you need a spending limit.## 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.+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); backlink, domain, ranking, live-search, and keyword lookups spend credits. The skill expands research when it can change the diagnosis or priority, reuses relevant evidence, and respects explicit budgets. Cost varies with the investigation rather than a fixed lookup allowance.## Read the actual skill@@ -52,6 +55,6 @@ The source `SKILL.md` lives on GitHub:- [SEO Report](/docs/skills/seo-report), the shared skill that writes and saves the report.- [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.+- [Keyword Research](/docs/skills/keyword-research) to build the keyword plan behind a recommendation.+- [Link Prospecting](/docs/skills/link-prospecting) when the report recommends link outreach 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-report.mdx b/web/content/docs/skills/seo-report.mdxindex 48d112d1..5ba5cd58 100644--- a/web/content/docs/skills/seo-report.mdx+++ b/web/content/docs/skills/seo-report.mdx@@ -14,7 +14,8 @@ You do not run it on its own. When your agent finishes an audit, a keyword study- Check `list_reports` first and update the existing report when it is correcting its own run, instead of leaving you with three near-identical copies.- Keep the report self-contained: all the styling is inside the file, nothing is fetched from the web, and it prints correctly with no network at all.- Write a short summary alongside the page, so the agent, or the next agent, can pick the work back up without re-reading the whole report.-- Reply in chat with the link, the verdict, and the top action, and leave the tables where they belong.+- Explain the expected benefit beside each recommendation, distinguishing measured outcomes from estimates and hypotheses.+- Reply in chat with the link, the verdict, and the leading recommendation with its expected benefit, if supported.## What you get back