Skip to content
Back to search

seo-readout

SkillWorks with Claude CodeGitHub

Claude skills that turn GA4, Search Console and Google Ads exports into answers a client can read

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/briefreelancing--seo-readout/badge.svg)](/listings/briefreelancing--seo-readout)

HTML

<a href="/listings/briefreelancing--seo-readout"><img src="/api/listings/briefreelancing--seo-readout/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

In Claude (web or desktop)

Follow the [No-code setup guide](docs/no-code-setup.md). To build the zips yourself instead of downloading them from a release, run `python tools/package_skills.py`; they appear in `dist/`.

In Claude Code

Copy the skill folders into your skills directory:

cp -r skills/traffic-aggregator ~/.claude/skills/readout-traffic-aggregator
cp -r skills/change-explainer ~/.claude/skills/readout-change-explainer

From the command line, without Claude

The scripts run on their own:

pip install -r requirements.txt
python skills/traffic-aggregator/scripts/aggregate.py sample-data/northwind-bakery --out out/aggregate
python skills/change-explainer/scripts/explain.py sample-data/northwind-bakery \
  --events sample-data/northwind-bakery/events.csv --brand-terms "northwind" --out out/explain

You get all the numbers and charts. The written explanation is the part Claude adds.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 164 lines
  1. <img src="docs/images/readout-logo.png" alt="Readout logo" width="110">
  2. # Readout
  3. **Claude skills that turn GA4, Search Console and Google Ads exports into answers a client can read.**
  4. Readout is a free, open toolkit for SEO, GEO and marketing consultants. Drop in the exports you
  5. already download, and get back clean combined data, a health check, and a plain-language
  6. explanation of what changed and why.
  7. It is built on one rule: **scripts calculate, Claude explains.** Every number in a Readout
  8. summary or report comes from Python, not from the language model. The report builder refuses
  9. to publish a narrative containing a number it can't trace back to the calculated results.
  10. ## Start here (no coding needed)
  11. 1. **Download** `readout-traffic-aggregator.zip` and `readout-change-explainer.zip` from the
  12. [latest release](../../releases/latest). Don't unzip them.
  13. 2. **In Claude, turn on code execution:** Settings > Capabilities > Code execution and file creation.
  14. 3. **Upload both zips** under Skills (Create skill > Upload a skill), and switch them on.
  15. 4. **Start a chat**, attach your exports, and ask: *"Why did search traffic drop last month?"*
  16. Step-by-step help with troubleshooting: [No-code setup guide](docs/no-code-setup.md).
  17. How to get your data out of Google's tools: [Export guide](docs/exporting-data.md).
  18. ![Example change report](docs/images/report-preview.png)
  19. ## Skills
  20. | Skill | What it answers | Outputs |
  21. |---|---|---|
  22. | [`traffic-aggregator`](skills/traffic-aggregator/SKILL.md) | "Give me one clean view of all my data." Merges GA4, Search Console and Google Ads, checks data health, summarizes channels, and shows numbers that never match side by side. | Chat summary, Excel workbook, standard CSV, charts |
  23. | [`change-explainer`](skills/change-explainer/SKILL.md) | "Why did traffic drop?" Six questions in order: Is it real? Is it unusual? Where? What kind of change? When did it start? What should be checked next? | Chat summary, client-ready HTML report, charts |
  24. Both skills accept exports exactly as downloaded: Search Console zips, GA4 CSVs with their
  25. comment lines, Google Ads reports with title rows and totals. No reformatting, no API keys.
  26. ## Who it's for
  27. Solo SEO and GEO consultants reporting to several clients, one client at a time. The data
  28. work that usually eats an afternoon (combining exports, checking for tracking gaps, finding
  29. which pages moved, lining the drop up with site changes and Google updates) takes a few
  30. minutes, and the result is written for the client, not for an analyst.
  31. ## Quick start
  32. ### In Claude (web or desktop)
  33. Follow the [No-code setup guide](docs/no-code-setup.md). To build the zips yourself instead of
  34. downloading them from a release, run `python tools/package_skills.py`; they appear in `dist/`.
  35. ### In Claude Code
  36. Copy the skill folders into your skills directory:
  37. ```bash
  38. cp -r skills/traffic-aggregator ~/.claude/skills/readout-traffic-aggregator
  39. cp -r skills/change-explainer ~/.claude/skills/readout-change-explainer
  40. ```
  41. ### From the command line, without Claude
  42. The scripts run on their own:
  43. ```bash
  44. pip install -r requirements.txt
  45. python skills/traffic-aggregator/scripts/aggregate.py sample-data/northwind-bakery --out out/aggregate
  46. python skills/change-explainer/scripts/explain.py sample-data/northwind-bakery \
  47. --events sample-data/northwind-bakery/events.csv --brand-terms "northwind" --out out/explain
  48. ```
  49. You get all the numbers and charts. The written explanation is the part Claude adds.
  50. ## Try it with the sample data
  51. `sample-data/` holds synthetic exports for two fictional clients, each with a story built in:
  52. - `northwind-bakery/`: three blog posts lose rankings the day after a site redesign, and GA4
  53. tracking breaks for one day.
  54. - `lakeview-plumbing/`: service pages gain rankings a few days after a content refresh, and a
  55. Google Ads campaign is paused.
  56. The finished outputs are in [`examples/northwind-bakery/`](examples/northwind-bakery/),
  57. including the [client report](examples/northwind-bakery/explain/report.html).
  58. ## How it works
  59. ```
  60. exports ─► load (detect source, read messy formats) ─► standard daily table
  61. │
  62. health checks ◄───────────────────────────────┤
  63. channel summary, side by side ◄───────────────┤ traffic-aggregator
  64. six-question diagnosis ◄──────────────────────┘ change-explainer
  65. │
  66. findings.json ─► Claude writes narrative ─► number check ─► report
  67. ```
  68. Design choices:
  69. - **Numbers from tools that measure different things are never added together.** Search Console
  70. clicks, GA4 sessions and Google Ads clicks are shown side by side, with the reasons they differ.
  71. A sudden change in the gap is flagged as a possible tracking problem.
  72. - **Tracking is checked before anything is diagnosed.** Near-zero days, every channel dropping
  73. at once, and shifts in the GA4 to Search Console ratio are caught first. On small sites,
  74. ordinary zero-click days are not mistaken for tracking gaps.
  75. - **"Coincides with", never "caused by".** The trend shift is matched to your own event log and
  76. to a dated list of Google updates. Timing is reported as timing.
  77. - **Seasonality is tested, not assumed.** Each change is compared with this site's normal
  78. 28-day swings and with the same weeks last year.
  79. ## Repo structure
  80. ```
  81. readout/
  82. ├── skills/
  83. │ ├── traffic-aggregator/ SKILL.md, scripts/, references/
  84. │ └── change-explainer/ SKILL.md, scripts/, references/ (Google update list), templates/
  85. ├── shared/readout_core/ source of truth for shared code (copied into each skill)
  86. ├── docs/ exporting guide, channel grouping
  87. ├── sample-data/ synthetic exports for two fictional clients
  88. ├── examples/ finished outputs from the sample data
  89. ├── tools/ sync shared code, package skills, make sample data
  90. └── tests/
  91. ```
  92. Each skill carries its own copy of `readout_core` so it works when uploaded on its own. Edit
  93. `shared/readout_core`, then run `python tools/sync_shared.py`. CI fails if a copy is out of date.
  94. ## Limits
  95. - **Export formats** were built from commonly seen layouts and tested on synthetic files plus one
  96. real 16-month Search Console export from a small site. GA4 and Google Ads parsers have not yet
  97. been tested on real exports. If a file isn't recognized, Readout says which one and why.
  98. Issues with anonymized examples are very welcome.
  99. - Numbers must use US formatting (1,234.56).
  100. - Thresholds that label patterns ("unusual", "ranking loss") are rules of thumb, listed in
  101. `findings.json` so they can be questioned.
  102. - The Google update list is maintained by hand. The skill warns when a trend shift is newer
  103. than the list.
  104. ## Roadmap
  105. - Stakeholder translator: the same data written for executives, developers, sales and content
  106. - AI referral segmenter: separate ChatGPT, Perplexity and similar referrals in GA4
  107. - SEO ticket writer: audit findings to developer tickets with acceptance criteria
  108. - More sources: Meta Ads, email platforms
  109. - Portfolio view across clients
  110. - Optional GA4 and Search Console connectors instead of exports
  111. ## Contributing
  112. The most useful contributions right now:
  113. 1. **Real export samples** (anonymized) that Readout fails to read.
  114. 2. **Google update list entries** in `skills/change-explainer/references/google_updates.csv`,
  115. with a link to Google's Search Status Dashboard. Update `last_updated` in the `.meta.json` file.
  116. Run `python -m pytest -q` before opening a pull request.
  117. ## License
  118. MIT. See [LICENSE](LICENSE).
  119. Built by Brie.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.