Skip to content

Open source alternative to Semrush and Ahrefs

Document how SEO reports are made (#627)

Ben Senescu43832867dafd
diff --git a/.agents/skills/competitive-landscape/SKILL.md b/.agents/skills/competitive-landscape/SKILL.md
index 5714761c..7c0c1f62 100644
--- a/.agents/skills/competitive-landscape/SKILL.md
+++ b/.agents/skills/competitive-landscape/SKILL.md
@@ -76,7 +76,7 @@ Sections in this order:
3. **Why they win** — one finding per pattern, the Fix pointing at what the user should do instead.
4. **Gaps and openings** — a table of theme, demand, and who currently owns it, plus a bar chart when a handful of themes carry the demand.
5. **What to do next** — an ordered list ending in the next workflow to run: competitor analysis, keyword clustering, or a content brief.
-6. **Method** — the query set used, and a note calling the read directional when the query set was small.
+6. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/competitive-landscape` ("OpenSEO Competitive Landscape skill"), then the query set used, and a note calling the read directional when the query set was small.
## Guardrails
diff --git a/.agents/skills/competitor-analysis/SKILL.md b/.agents/skills/competitor-analysis/SKILL.md
index a6d00ef9..1b2f7919 100644
--- a/.agents/skills/competitor-analysis/SKILL.md
+++ b/.agents/skills/competitor-analysis/SKILL.md
@@ -79,7 +79,7 @@ Sections in this order:
4. **Keyword themes** — a table of theme, example keywords, volume, and whether the user competes there. A bar chart when a few themes dominate the footprint.
5. **Content patterns and authority** — prose, with a note for anything inferred from keyword rows rather than seen on a page.
6. **What to do next** — an ordered list, shortest useful.
-7. **Method** — which tools reported what, and what you checked yourself.
+7. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/competitor-analysis` ("OpenSEO Competitor Analysis skill"), then which tools reported what, and what you checked yourself.
## Guardrails
diff --git a/.agents/skills/keyword-clustering/SKILL.md b/.agents/skills/keyword-clustering/SKILL.md
index 9ed4e4d5..abd6ed18 100644
--- a/.agents/skills/keyword-clustering/SKILL.md
+++ b/.agents/skills/keyword-clustering/SKILL.md
@@ -72,7 +72,7 @@ Sections in this order:
3. **Page briefs** — one finding per cluster: the page type and the searcher's problem, then the page to create or update. List required sections and internal links underneath.
4. **Cannibalization** — a table of the query, the competing URLs, and which one to keep, only when there is real evidence for it.
5. **What to do next** — an ordered list, including the tag suggestions and the explicit ask before applying them.
-6. **Method** — where the keywords came from, and a note labelling target pages as proposed when no URL data was supplied.
+6. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/keyword-clustering` ("OpenSEO Keyword Clustering skill"), then where the keywords came from, and a note labelling target pages as proposed when no URL data was supplied.
## Guardrails
diff --git a/.agents/skills/keyword-research/SKILL.md b/.agents/skills/keyword-research/SKILL.md
index 24923bd5..ba553510 100644
--- a/.agents/skills/keyword-research/SKILL.md
+++ b/.agents/skills/keyword-research/SKILL.md
@@ -74,7 +74,7 @@ Sections in this order:
4. **The longer opportunity list** — a second table, same columns.
5. **Risks and caveats** — notes: SERP intent that would change the recommendation, missing metrics written as `unknown`, close-variant volumes that are one bucket rather than several.
6. **What to do next** — an ordered list, including whether to run keyword clustering, write a content brief, or save the chosen keywords.
-7. **Method** — which tools returned what.
+7. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/keyword-research` ("OpenSEO Keyword Research skill"), then which tools returned what.
## Guardrails
diff --git a/.agents/skills/link-prospecting/SKILL.md b/.agents/skills/link-prospecting/SKILL.md
index ec1248e3..eb676eae 100644
--- a/.agents/skills/link-prospecting/SKILL.md
+++ b/.agents/skills/link-prospecting/SKILL.md
@@ -106,7 +106,7 @@ Sections in this order:
4. **Outreach drafts** — the message text for each of two or three reusable angles: resource or list inclusion, an article update, and a comparison mention.
5. **Limitations** — notes: contact paths not found, prospects that are direct competitors or likely paid placements, and which source found each contact detail.
6. **What to do next** — an ordered list: who to send to first, and in what order.
-7. **Method** — which tools returned prospects and which came from the web or the browser.
+7. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/link-prospecting` ("OpenSEO Link Prospecting skill"), then which tools returned prospects and which came from the web or the browser.
## Guardrails
diff --git a/.agents/skills/local-seo/SKILL.md b/.agents/skills/local-seo/SKILL.md
index 59dd9c36..5794061c 100644
--- a/.agents/skills/local-seo/SKILL.md
+++ b/.agents/skills/local-seo/SKILL.md
@@ -74,7 +74,7 @@ Sections in this order:
4. **Maps coverage** — what the grid shows, where visibility drops off, and who wins there. A bar chart of ranks by direction reads faster than a paragraph; label every value.
5. **Q&A and posting** — only when the basics are already competitive.
6. **What to do next** — an ordered list.
-7. **Method** — which tools returned what, plus a note reading each missing grid rank against that point's `resultsCount` rather than calling it invisibility.
+7. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/local-seo` ("OpenSEO Local SEO skill"), then which tools returned what, plus a note reading each missing grid rank against that point's `resultsCount` rather than calling it invisibility.
## Guardrails
diff --git a/.agents/skills/seo-audit/SKILL.md b/.agents/skills/seo-audit/SKILL.md
index 275e6217..1a41c92d 100644
--- a/.agents/skills/seo-audit/SKILL.md
+++ b/.agents/skills/seo-audit/SKILL.md
@@ -70,7 +70,7 @@ Sections in this order:
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. **Method** — what the tools reported and what you verified by hand.
+7. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/seo-audit` ("OpenSEO SEO Audit skill"), then what the tools reported and what you verified by hand.
Use a note for anything you could not verify or where the site's goal makes a standard recommendation the wrong call.
diff --git a/.agents/skills/seo-report/SKILL.md b/.agents/skills/seo-report/SKILL.md
index 969af63f..3e45ddeb 100644
--- a/.agents/skills/seo-report/SKILL.md
+++ b/.agents/skills/seo-report/SKILL.md
@@ -25,7 +25,7 @@ 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 footer, not in the section.
+- **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.
- **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.
@@ -37,6 +37,16 @@ Use a template only when the user names it, or asks for the kind of report a tem
- `title`: names the subject and the period, under 120 characters. "badseo.dev SEO audit, Sep 2026". Never "SEO Report" or "Analysis".
- `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.
+## 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.
+
+```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>
+```
+
+The URL is always `https://openseo.so/docs/skills/` followed by the skill's directory name, exactly as written in that skill's Output format list. Copy it; do not guess a slug. Then the rest of the section as the skill describes it: which tools reported what, and what you verified by hand. A report written from a template keeps this section too, as its last one.
+
## HTML constraints
These are enforced by the viewer, not by taste. A report that breaks them renders blank or broken.
@@ -166,6 +176,7 @@ footer{max-width:660px;margin:64px 0 0;padding:26px 0 0;border-top:1px solid var
<ol>
<li><a href="#section-heading">SECTION HEADING</a></li>
<li><a href="#what-to-do-next">What to do next</a></li>
+ <li><a href="#how-this-report-was-made">How this report was made</a></li>
</ol>
</nav>
</div></aside>
@@ -202,10 +213,17 @@ footer{max-width:660px;margin:64px 0 0;padding:26px 0 0;border-top:1px solid var
<h2 id="what-to-do-next">What to do next</h2>
<ol><li>The top priority, first.</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>
+ <ul class="finding">
+ <li><b>Tools:</b> which OpenSEO tools reported which numbers.</li>
+ <li><b>Verified:</b> what you checked against the live site by hand.</li>
+ </ul>
+
</article>
</div>
-<footer>What the tools reported, and what was verified by hand.</footer>
+<footer>Prepared with OpenSEO. Data as of MONTH D, YYYY.</footer>
</div></body></html>
```
@@ -219,7 +237,8 @@ footer{max-width:660px;margin:64px 0 0;padding:26px 0 0;border-top:1px solid var
- **`.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.
- **`hr` then a closing `h2`** — the "What to do next" list, ordered, shortest useful.
-- **`footer`** — what the tools reported and what you verified by hand.
+- **How this report was made** — the last `h2`: the skill link line, then Tools and Verified bullets. See the section above.
+- **`footer`** — one line: the sign-off and the data date. Method detail belongs in the closing section, not here.
## Guardrails
diff --git a/plugins/openseo/skills/competitive-landscape/SKILL.md b/plugins/openseo/skills/competitive-landscape/SKILL.md
index 5714761c..7c0c1f62 100644
--- a/plugins/openseo/skills/competitive-landscape/SKILL.md
+++ b/plugins/openseo/skills/competitive-landscape/SKILL.md
@@ -76,7 +76,7 @@ Sections in this order:
3. **Why they win** — one finding per pattern, the Fix pointing at what the user should do instead.
4. **Gaps and openings** — a table of theme, demand, and who currently owns it, plus a bar chart when a handful of themes carry the demand.
5. **What to do next** — an ordered list ending in the next workflow to run: competitor analysis, keyword clustering, or a content brief.
-6. **Method** — the query set used, and a note calling the read directional when the query set was small.
+6. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/competitive-landscape` ("OpenSEO Competitive Landscape skill"), then the query set used, and a note calling the read directional when the query set was small.
## Guardrails
diff --git a/plugins/openseo/skills/competitor-analysis/SKILL.md b/plugins/openseo/skills/competitor-analysis/SKILL.md
index a6d00ef9..1b2f7919 100644
--- a/plugins/openseo/skills/competitor-analysis/SKILL.md
+++ b/plugins/openseo/skills/competitor-analysis/SKILL.md
@@ -79,7 +79,7 @@ Sections in this order:
4. **Keyword themes** — a table of theme, example keywords, volume, and whether the user competes there. A bar chart when a few themes dominate the footprint.
5. **Content patterns and authority** — prose, with a note for anything inferred from keyword rows rather than seen on a page.
6. **What to do next** — an ordered list, shortest useful.
-7. **Method** — which tools reported what, and what you checked yourself.
+7. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/competitor-analysis` ("OpenSEO Competitor Analysis skill"), then which tools reported what, and what you checked yourself.
## Guardrails
diff --git a/plugins/openseo/skills/keyword-clustering/SKILL.md b/plugins/openseo/skills/keyword-clustering/SKILL.md
index 9ed4e4d5..abd6ed18 100644
--- a/plugins/openseo/skills/keyword-clustering/SKILL.md
+++ b/plugins/openseo/skills/keyword-clustering/SKILL.md
@@ -72,7 +72,7 @@ Sections in this order:
3. **Page briefs** — one finding per cluster: the page type and the searcher's problem, then the page to create or update. List required sections and internal links underneath.
4. **Cannibalization** — a table of the query, the competing URLs, and which one to keep, only when there is real evidence for it.
5. **What to do next** — an ordered list, including the tag suggestions and the explicit ask before applying them.
-6. **Method** — where the keywords came from, and a note labelling target pages as proposed when no URL data was supplied.
+6. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/keyword-clustering` ("OpenSEO Keyword Clustering skill"), then where the keywords came from, and a note labelling target pages as proposed when no URL data was supplied.
## Guardrails
diff --git a/plugins/openseo/skills/keyword-research/SKILL.md b/plugins/openseo/skills/keyword-research/SKILL.md
index 24923bd5..ba553510 100644
--- a/plugins/openseo/skills/keyword-research/SKILL.md
+++ b/plugins/openseo/skills/keyword-research/SKILL.md
@@ -74,7 +74,7 @@ Sections in this order:
4. **The longer opportunity list** — a second table, same columns.
5. **Risks and caveats** — notes: SERP intent that would change the recommendation, missing metrics written as `unknown`, close-variant volumes that are one bucket rather than several.
6. **What to do next** — an ordered list, including whether to run keyword clustering, write a content brief, or save the chosen keywords.
-7. **Method** — which tools returned what.
+7. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/keyword-research` ("OpenSEO Keyword Research skill"), then which tools returned what.
## Guardrails
diff --git a/plugins/openseo/skills/link-prospecting/SKILL.md b/plugins/openseo/skills/link-prospecting/SKILL.md
index ec1248e3..eb676eae 100644
--- a/plugins/openseo/skills/link-prospecting/SKILL.md
+++ b/plugins/openseo/skills/link-prospecting/SKILL.md
@@ -106,7 +106,7 @@ Sections in this order:
4. **Outreach drafts** — the message text for each of two or three reusable angles: resource or list inclusion, an article update, and a comparison mention.
5. **Limitations** — notes: contact paths not found, prospects that are direct competitors or likely paid placements, and which source found each contact detail.
6. **What to do next** — an ordered list: who to send to first, and in what order.
-7. **Method** — which tools returned prospects and which came from the web or the browser.
+7. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/link-prospecting` ("OpenSEO Link Prospecting skill"), then which tools returned prospects and which came from the web or the browser.
## Guardrails
diff --git a/plugins/openseo/skills/local-seo/SKILL.md b/plugins/openseo/skills/local-seo/SKILL.md
index 59dd9c36..5794061c 100644
--- a/plugins/openseo/skills/local-seo/SKILL.md
+++ b/plugins/openseo/skills/local-seo/SKILL.md
@@ -74,7 +74,7 @@ Sections in this order:
4. **Maps coverage** — what the grid shows, where visibility drops off, and who wins there. A bar chart of ranks by direction reads faster than a paragraph; label every value.
5. **Q&A and posting** — only when the basics are already competitive.
6. **What to do next** — an ordered list.
-7. **Method** — which tools returned what, plus a note reading each missing grid rank against that point's `resultsCount` rather than calling it invisibility.
+7. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/local-seo` ("OpenSEO Local SEO skill"), then which tools returned what, plus a note reading each missing grid rank against that point's `resultsCount` rather than calling it invisibility.
## Guardrails
diff --git a/plugins/openseo/skills/seo-audit/SKILL.md b/plugins/openseo/skills/seo-audit/SKILL.md
index 275e6217..1a41c92d 100644
--- a/plugins/openseo/skills/seo-audit/SKILL.md
+++ b/plugins/openseo/skills/seo-audit/SKILL.md
@@ -70,7 +70,7 @@ Sections in this order:
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. **Method** — what the tools reported and what you verified by hand.
+7. **How this report was made** — opens with the skill link line from `seo-report`, pointing at `https://openseo.so/docs/skills/seo-audit` ("OpenSEO SEO Audit skill"), then what the tools reported and what you verified by hand.
Use a note for anything you could not verify or where the site's goal makes a standard recommendation the wrong call.
diff --git a/plugins/openseo/skills/seo-report/SKILL.md b/plugins/openseo/skills/seo-report/SKILL.md
index 969af63f..3e45ddeb 100644
--- a/plugins/openseo/skills/seo-report/SKILL.md
+++ b/plugins/openseo/skills/seo-report/SKILL.md
@@ -25,7 +25,7 @@ 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 footer, not in the section.
+- **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.
- **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.
@@ -37,6 +37,16 @@ Use a template only when the user names it, or asks for the kind of report a tem
- `title`: names the subject and the period, under 120 characters. "badseo.dev SEO audit, Sep 2026". Never "SEO Report" or "Analysis".
- `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.
+## 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.
+
+```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>
+```
+
+The URL is always `https://openseo.so/docs/skills/` followed by the skill's directory name, exactly as written in that skill's Output format list. Copy it; do not guess a slug. Then the rest of the section as the skill describes it: which tools reported what, and what you verified by hand. A report written from a template keeps this section too, as its last one.
+
## HTML constraints
These are enforced by the viewer, not by taste. A report that breaks them renders blank or broken.
@@ -166,6 +176,7 @@ footer{max-width:660px;margin:64px 0 0;padding:26px 0 0;border-top:1px solid var
<ol>
<li><a href="#section-heading">SECTION HEADING</a></li>
<li><a href="#what-to-do-next">What to do next</a></li>
+ <li><a href="#how-this-report-was-made">How this report was made</a></li>
</ol>
</nav>
</div></aside>
@@ -202,10 +213,17 @@ footer{max-width:660px;margin:64px 0 0;padding:26px 0 0;border-top:1px solid var
<h2 id="what-to-do-next">What to do next</h2>
<ol><li>The top priority, first.</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>
+ <ul class="finding">
+ <li><b>Tools:</b> which OpenSEO tools reported which numbers.</li>
+ <li><b>Verified:</b> what you checked against the live site by hand.</li>
+ </ul>
+
</article>
</div>
-<footer>What the tools reported, and what was verified by hand.</footer>
+<footer>Prepared with OpenSEO. Data as of MONTH D, YYYY.</footer>
</div></body></html>
```
@@ -219,7 +237,8 @@ footer{max-width:660px;margin:64px 0 0;padding:26px 0 0;border-top:1px solid var
- **`.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.
- **`hr` then a closing `h2`** — the "What to do next" list, ordered, shortest useful.
-- **`footer`** — what the tools reported and what you verified by hand.
+- **How this report was made** — the last `h2`: the skill link line, then Tools and Verified bullets. See the section above.
+- **`footer`** — one line: the sign-off and the data date. Method detail belongs in the closing section, not here.
## Guardrails