/seo-report

name: seo-report
description: "Write and save an OpenSEO report as one self-contained HTML page. Use when a skill has finished its research, and whenever the user asks for a report, check-in, or summary, or names a report template."

OpenSEO Report

Goal

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 leading recommendation with its expected benefit, if there is one. The report gets everything else.

Before you write

1. Call `list_reports` for the project. If a report already covers the same subject for the same period, you are correcting your own run: pass its `reportId` to `save_report` and replace it. A new month, a new competitor, or a different skill is a new report. Never save a near-duplicate. 2. Titles are unique within a project. Saving a second report under an existing title with no `reportId` is rejected, so either pass the `reportId` of the report you are replacing or change the title to name the new subject or period. 3. To revise an existing report, work from its summary. `get_report` returns the HTML only with `includeHtml: true`, and an 80 KB report is roughly 20,000 tokens, which most clients truncate. Fetch the HTML only when you need to edit a specific passage, and if what comes back looks cut off, send the user to the app instead of saving over it.

Following a template

A project can carry report templates: named, reusable briefs saying who a report is for, which sections it has in what order, how it should sound, and how to sign off. They are listed in project context, and `list_report_templates` returns the full instructions for each one. Templates belong to a project. To reuse one in another project, list it there and save a copy here.

Use a template only when the user names it, or asks for the kind of report a template's name or description names. A plain skill run ("audit this site") uses the skill's default format. If two match, ask in one line. A template's sections, audience and tone replace the skill's Output format list; the HTML constraints and writing rules never change. Project writing_preferences always apply; a template's tone wins only where they conflict. Pass its `templateId` to `save_report`.

Writing rules

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

• `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 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 e