Skip to content
Back to search

seo-operator

MarketplaceWorks with Claude CodeGitHub

SEO as a weekly loop: measure, pick the one change worth the next hour, do it, check later whether it worked.

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/mavrin-xv--seo-operator/badge.svg)](/listings/mavrin-xv--seo-operator)

HTML

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

Install

Install instructions from the README

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

1. Export the Pages and Queries tables from Search Console (Performance, last 28 days) as CSV. 2. In Claude Code:

   > do SEO for acme-coffee.com. Exports are in ~/Downloads/gsc. Money pages: /subscriptions, /wholesale

3. The agent creates `.seo/acme-coffee/`, measures, crawls, shows the board, does the top action with you, registers it, and writes a report. Next week, say "SEO run for acme-coffee" and it starts by verifying the old actions.

Try it offline on the invented coffee roaster first:

cd skills/seo-operator/scripts
SEO_STATE_DIR=../../../examples/acme-coffee/state python3 seo_select.py acme-coffee --today 2026-11-20
board for acme-coffee on 2026-11-20 (22 candidates, 2 skipped)
#    score   kind          lane    target / why
1    219.2   title-meta    ctr     /blog/how-to-make-cold-brew
                           CTR 1.2% vs 3.1% expected at position 7.2
2    100.0   link-fix      links   /wholesale  [money page]
                           internal links point at a redirect
3    75.2    title-meta    ctr     /subscriptions  [money page]
                           CTR 1.5% vs 3.9% expected at position 6.1
...
skipped title-meta /: in ctr_skip_paths (brand searches set a home page's CTR)
skipped title-meta /menu/cold-brew: cooldown

Every other example output sits next to its input in `examples/acme-coffee/`.

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.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "name": "seo-operator",
  3. "plugins": [
  4. {
  5. "name": "seo-operator",
  6. "source": "./",
  7. "description": "SEO for a site you own, run as a loop: per-site memory, Search Console and crawl vitals, every action ranked by clicks per operator-hour, a ledger that checks weeks later whether each change worked, plus technical probes, title and description lint, query research, llms.txt and markdown mirrors, AI citation tracking and a single-page audit.",
  8. "version": "0.1.0"
  9. }
  10. ],
  11. "owner": {
  12. "name": "Artem Mavrin",
  13. "url": "https://github.com/mavrin-xv"
  14. }
  15. }
README.md · README · 147 lines
  1. ![seo-operator](assets/banner.png)
  2. # seo-operator
  3. **SEO for a site you own, run as a weekly loop by Claude Code: it measures, picks the one change worth the next hour, does it, and checks weeks later whether it worked.**
  4. Most SEO help is an audit: sixty findings, no order, and nobody finds out which fixes moved anything. This pack keeps memory per site in plain files, ranks every possible action on one scale (clicks at stake per operator-hour), and keeps a ledger that judges each change against the site-wide trend after 21 days. Around the loop sit the jobs that come up every week: technical probes, titles and descriptions, query research, llms.txt and markdown mirrors, AI citation tracking and a single-page audit.
  5. ![License: MIT](https://img.shields.io/badge/license-MIT-blue) ![Works with Claude Code](https://img.shields.io/badge/works%20with-Claude%20Code-orange) ![Python 3.9+ stdlib](https://img.shields.io/badge/python-3.9%2B%20stdlib-green)
  6. ![Example output](assets/example.png)
  7. ```bash
  8. git clone https://github.com/mavrin-xv/seo-operator && cd seo-operator
  9. ./install.sh # skills into ~/.claude/skills (or --project for this project only)
  10. ```
  11. <!-- install-notes:start -->
  12. Other ways in: as a Claude Code plugin, run `/plugin marketplace add mavrin-xv/seo-operator` and then `/plugin install seo-operator@seo-operator`. For Codex or another agent that reads `SKILL.md`, copy the folders under `skills/` into its skills directory. On Windows, run `install.sh` from Git Bash or WSL and type `py -3` where these docs say `python3`.
  13. <!-- install-notes:end -->
  14. ## What it solves
  15. | Pain | What the pack does |
  16. |---|---|
  17. | An audit with 60 findings and no order | One board: every action scored as clicks at stake x share usually recovered / hours, money pages x1.5 |
  18. | "Did that title change work?" Nobody knows | A ledger pins the baseline on the day of the change and judges it after 21+ days against the site trend |
  19. | Every page is up 20% and the fix gets the credit | Verify subtracts the site-wide change before calling anything a win |
  20. | The next session starts from zero | Per-site state folder: config, snapshots, board, ledger, facts, owner to-do |
  21. | robots.txt allows AI bots, the CDN blocks them | Probes each crawler's user agent against a browser request, and reads robots groups per crawler |
  22. | Titles stuffed with keywords or numbers nobody can back up | A lint with hard fails and 30 automatic points; numbers must appear in your facts file |
  23. | A content plan built from ideas | Query buckets, striking-distance queries and autocomplete, filed as NOW, NEXT, HOLD or DROP |
  24. | "Does ChatGPT recommend us?" answered by one screenshot | Dated rounds of fixed prompts, share of model per engine, failed checks kept out of the count |
  25. ## What's inside
  26. | Skill | What it does | Say |
  27. |---|---|---|
  28. | [seo-operator](skills/seo-operator/SKILL.md) | The loop: memory, measure, crawl, rank, act, register, verify, report | "do SEO for my site", "what should I fix this week" |
  29. | [site-health](skills/site-health/SKILL.md) | Crawl plus live probes: soft 404, robots groups, edge blocks, JS-only pages, redirect chains, swapped-name pages | "technical SEO audit", "are AI bots blocked" |
  30. | [serp-copy](skills/serp-copy/SKILL.md) | Title and description variants by angle, linted and scored, one shipped and registered | "rewrite the title", "improve CTR" |
  31. | [page-audit](skills/page-audit/SKILL.md) | One page or draft scored GEO 60, SEO 30, brand 10 from counted facts, with exact fixes | "audit this draft", "will ChatGPT cite this" |
  32. | [query-research](skills/query-research/SKILL.md) | Intent buckets, striking distance, autocomplete, a decision queue | "what should we write about", "keyword research" |
  33. | [llms-txt-mirror](skills/llms-txt-mirror/SKILL.md) | llms.txt built from the crawl, markdown mirrors in a fixed layout, both linted | "make an llms.txt", "markdown version of our pages" |
  34. | [ai-citations](skills/ai-citations/SKILL.md) | Cited, mentioned or absent per engine and prompt, compared between rounds | "AI visibility", "share of model" |
  35. Scripts (Python standard library, each with `--help`): `seo_state.py`, `seo_measure.py`, `seo_crawl.py`, `seo_select.py`, `seo_register.py`, `seo_report.py`, `site_probe.py`, `overlap.py`, `serp_lint.py`, `page_facts.py`, `query_buckets.py`, `suggest.py`, `llms_txt.py`, `mirror_lint.py`, `aeo_diff.py`.
  36. ## Quick start
  37. 1. Export the Pages and Queries tables from Search Console (Performance, last 28 days) as CSV.
  38. 2. In Claude Code:
  39. ```
  40. > do SEO for acme-coffee.com. Exports are in ~/Downloads/gsc. Money pages: /subscriptions, /wholesale
  41. ```
  42. 3. The agent creates `.seo/acme-coffee/`, measures, crawls, shows the board, does the top action with you, registers it, and writes a report. Next week, say "SEO run for acme-coffee" and it starts by verifying the old actions.
  43. Try it offline on the invented coffee roaster first:
  44. ```bash
  45. cd skills/seo-operator/scripts
  46. SEO_STATE_DIR=../../../examples/acme-coffee/state python3 seo_select.py acme-coffee --today 2026-11-20
  47. ```
  48. ```
  49. board for acme-coffee on 2026-11-20 (22 candidates, 2 skipped)
  50. # score kind lane target / why
  51. 1 219.2 title-meta ctr /blog/how-to-make-cold-brew
  52. CTR 1.2% vs 3.1% expected at position 7.2
  53. 2 100.0 link-fix links /wholesale [money page]
  54. internal links point at a redirect
  55. 3 75.2 title-meta ctr /subscriptions [money page]
  56. CTR 1.5% vs 3.9% expected at position 6.1
  57. ...
  58. skipped title-meta /: in ctr_skip_paths (brand searches set a home page's CTR)
  59. skipped title-meta /menu/cold-brew: cooldown
  60. ```
  61. Every other example output sits next to its input in `examples/acme-coffee/`.
  62. ## How it works
  63. ```
  64. Search Console CSV/API the live site
  65. | |
  66. seo_measure seo_crawl + site_probe
  67. | |
  68. +------> .seo/<site>/ <--+ config, truth, radar, needs-you
  69. |
  70. seo_select --------> board: clicks at stake x recover / hours
  71. |
  72. act with one skill (serp-copy, page-audit, site-health, ...)
  73. |
  74. seo_register add ----> ledger: baseline + site totals
  75. |
  76. 21+ days later: seo_register verify (vs the site trend)
  77. |
  78. seo_report --------> reports/<date>.md
  79. ```
  80. Details: [docs/architecture.md](docs/architecture.md) and [docs/scoring.md](docs/scoring.md).
  81. ## Configure
  82. | What | Where |
  83. |---|---|
  84. | Domain, hosts, money pages, brand terms, excluded paths | `.seo/<site>/config.json` (from `templates/config.json`) |
  85. | Thresholds (TTFB, CTR position cap, cooldown, verify wait) | `thresholds` in the same file |
  86. | Your own effort and recovery numbers per action kind | `effort` and `recover` in the same file |
  87. | Facts copy may use | `.seo/<site>/truth.md` |
  88. | State folder location | `--state`, or `SEO_STATE_DIR` (use a relative path in Git Bash), default `./.seo` |
  89. | Search Console API | `GSC_ACCESS_TOKEN` in the environment, then `seo_measure.py --api` |
  90. ## Honest limits
  91. - Tested offline only, on the invented site in `examples/acme-coffee/` (a local copy served on 127.0.0.1). The scripts have not been run against a real site's Search Console account by the authors, and the `--api` path was not exercised.
  92. - The expected-CTR curve and the effort and recovery tables are starting guesses, not measurements. Replace them with your own ledger's numbers after about 10 verdicts per kind.
  93. - The crawler is a small stdlib crawler: no JavaScript rendering, a 300-page cap by default, and polite but simple rate handling. Big sites need a real crawler; feed its findings in by hand.
  94. - The edge-block probe sends spoofed user agents. A CDN that verifies crawlers by IP can treat this probe differently from the real crawler; confirm in the CDN's logs.
  95. - AI citation rounds are collected by hand or with an API you already have. No engine was queried while building this pack.
  96. - Search Console's UI export stops at 1,000 rows; large sites need the API.
  97. ## Credits
  98. - Operator loop with per-site memory and a verified ledger: the method comes from the authors' own practice; no outside code.
  99. - Technical check coverage and AI crawler handling: inspired by https://github.com/AgriciDaniel/claude-seo (MIT).
  100. - GEO scoring dimensions and citation tracking: inspired by https://github.com/zubair-trabzada/geo-seo-claude (MIT).
  101. - Search Console query patterns: inspired by https://github.com/AminForou/mcp-gsc (MIT).
  102. - llms.txt format: the proposal at https://llmstxt.org and https://github.com/AnswerDotAI/llms-txt (Apache-2.0).
  103. - Title, description and page audit checklists: inspired by https://github.com/coreyhaines31/marketingskills (MIT).
  104. - Repo and skill layout: modelled on https://github.com/anthropics/skills and https://github.com/obra/superpowers (MIT).
  105. Two scripts are adapted from https://github.com/boringmarketer/boring-marketing-skills (MIT, Copyright (c) 2026 Boring Marketing, LLC): `overlap.py` and `suggest.py`. Their headers list the changes; the license is in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). From everything else, ideas only; no code was copied.
  106. ## Contributing
  107. See [CONTRIBUTING.md](CONTRIBUTING.md). Agents working on the repo: [AGENTS.md](AGENTS.md).
  108. <!-- author:start -->
  109. ## Author
  110. Built and maintained by [Artem Mavrin](https://github.com/mavrin-xv). This repo is one of a set of agent skill packs for marketing and operations work. Each one installs on its own; the full list is in [agent-skill-packs](https://github.com/mavrin-xv/agent-skill-packs). If a pack saved you an afternoon, a star helps other people find it.
  111. <!-- author:end -->
  112. ## License
  113. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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