Claude Code SEO: Run a Weekly SEO Pass From Your Coding Agent (With Hard Limits)

Claude Code SEO works when the agent gets two things it does not have by default: real Search Console data, and hard limits on what it may change. Give Claude Code a skill that reads your site's search data through a CLI, caps each pass at 5 actions and 15 executions, keeps merges, redirects and noindex out of its hands, and ships everything as a pull request. Then the agent does the weekly SEO chores and you review one diff.

This page walks through that setup using the actual rules of the weekly SEO skill that PageSeeds ships, the same file Claude Code, Kimi or Grok runs. If you want the general idea of a terminal SEO agent first, read what an SEO CLI is. This post is about the Claude Code side: what the agent does each week and what it is not allowed to do.

Why a coding agent needs rails before it touches SEO

Ask Claude Code to "improve the SEO of this blog" with no data and no limits, and you get confident guesses. It rewrites titles that were already earning clicks, invents keywords, and touches forty files at once. Each edit can look reasonable. Together they are an unreviewable change set with no baseline to measure against.

Three things fix that:

1. Ground truth. The agent reads Google Search Console impressions, clicks, CTR and position through CLI tools that print JSON. The skill's first rule is that the agent never invents numbers.
2. A budget. A small, fixed number of changes per pass, so each one can be measured later.
3. A one-way door list. Actions that are expensive to undo (merges, redirects, slug changes, noindex) are taken away from the agent entirely.

The hard limits, straight from the skill

These are the rails in the weekly SEO skill. Breaking any of them fails the run.

| Rail | What the agent may do | Why | |------|----------------------|-----| | Budget | At most 5 created actions, 15 executions and 3 new articles per pass | Small change sets can be measured one by one | | Spacing | A mode-executing pass is refused if the last one ran less than 5 days ago; a measure-only pass is still allowed | Search Console needs time to show movement | | URL freeze | No merges, redirects or slug changes on published pages until the 2026-11-12 re-decision | Measured consolidations regressed 12 to 1 across projects | | Noindex | Never agent-run; listed under Needs your decision for a human | Deindexing is a one-way door | | Earning pages | A page with at least 1 click in the last 28 days gets no title or content rewrite; only an additive link, CTA or lead paragraph | Don't break what already works | | Workspace | All writes go into a separate git worktree; the run closes with a pull request | Nothing reaches the live checkout without review | | Product code | No edits to the tool's own source mid-run; a missing capability is reported as a gap | The agent operates the tool, it doesn't patch it |

The URL freeze has its own write-up: what happened to traffic after automated page merges. That result is why merges were taken away from the agent rather than left to its judgment.

What one weekly pass looks like

A pass is a fixed sequence. Claude Code runs it from the skill; you start it with /weekly-seo or a scheduler starts it for you.

1. Spacing gate. Check the newest weekly report's timestamp. Under 5 days: stop, or run measure-only.
2. Site-drop check. If Search Console shows an impressions cliff or missing data, stop before any new work and report it.
3. Outcome reviews first. Every earlier change schedules a review about 30 days later. All due reviews run before any new work counts toward the budget. They compare Search Console windows before and after the change, not a rank tracker.
4. Desk reads. A site overview (totals, top pages, freshness, striking-distance and declining-page lists), then per-page detail and query data for a few candidates.
5. Behavior check. A light PostHog read, 4 to 6 calls, to see whether search visitors bounce or reach the product. GSC stays the demand source.
6. Plan within the program's mode. The project's program file sets the week's mode: attract (new articles), harvest (send existing traffic to the product), tools, or measure.
7. Execute up to 5 actions through the CLI: write a new article, fix an existing one, add internal links.
8. Report and pull request. A dated Markdown report, a machine-readable outcome file, and a PR with only this run's content.

The agent does not wait for approval between steps. It states the plan and executes it. Its open questions are limited to the noindex rows a human must confirm.

Worked example: picking 5 actions on a small site

Say Search Console shows this for a 40-page blog (illustrative numbers):

| Page | Impressions (28d) | Avg position | Clicks (28d) | Agent's call | |------|-------------------|--------------|--------------|--------------| | /blog/pricing-guide | 420 | 9.8 | 0 | Fix: in the striking-distance band (position 7 to 13, about 200+ impressions); rewrite title and intro | | /blog/setup-tutorial | 310 | 11.2 | 4 | Leave the text alone: it earns clicks, so add one internal link at most | | /blog/old-comparison | 15 | 64.0 | 0 | No action; list it in the report | | /blog/merge-candidate-a + b | 90 / 60 | 30 / 35 | 0 | Not executed: merges are frozen; listed under Needs your decision | | (new) primary keyword | 0 | n/a | 0 | Write: one new article from the program's backlog |

That is three actions, under the cap of 5. Each change gets its own outcome review about 30 days later, so next month you can see which ones moved.

Setting it up with Claude Code

1. Install the CLI and register the site repo once with pageseeds-cli setup --path . --yes. Connect Search Console.
2. Add the skill. The weekly SEO skill is a Markdown file the agent loads. Claude Code finds it as a user skill, so /weekly-seo works in any repo.
3. Write the program file. seo_program.yaml sets the current mode and the queues (Primary keyword backlog, pages to harvest, prune candidates). A monthly review rewrites it. The weekly pass only reads it and updates row statuses.
4. Run it. Interactive: /weekly-seo my-site. Scheduled: the operator runner checks cadence, opens a worktree, starts the agent and ships the PR when the agent exits.
5. Review the PR. The report's Decisions made for you section lists every call the agent made, with the numbers behind it.

Claude Code SEO vs a dashboard tool

| | Coding agent + weekly skill | SEO dashboard | |---|---|---| | Output | Pull request with MDX changes + dated report | Charts and a to-do list | | Data | Your Search Console, read through a CLI | The vendor's crawl and keyword index | | Who executes | The agent, within 5 actions per pass | You, later | | Risky moves | Frozen or human-confirmed | Up to you | | Measurement | 30-day outcome review per change | Rank tracking |

A dashboard is still useful for broad keyword research. For the weekly "what do we change this week, and did last month's change work" loop, the agent plus rails is faster. See the 120-minute weekly SEO workflow for the manual version of the same loop, and what an AI SEO agent ships for where dashboards still win.

When this setup is the wrong call

• No Search Console data yet. With zero impressions there is nothing to measure. Write pages first; the weekly pass becomes useful once the site has data.
• A large site with an SEO team. Five actions a week is a deliberate ceiling. A team shipping dozens of changes a week needs a different process.
• You won't review PRs. The pull request is the review step. If nobody reads it, the rails can't protect you.

FAQ

Can Claude Code do SEO?

Yes, if you give it real data and a bounded job. On its own a coding agent can edit MDX and metadata, but it has no Search Console data and no limits. Run it with a skill that reads Search Console through a CLI, caps the number of changes per pass, and ships the result as a pull request you review.

What should a coding agent never do on its own for SEO?

Anything that is hard to undo. In the PageSeeds weekly skill, page merges, redirects and slug changes on published pages are frozen, and noindex is never agent-run: noindex rows are listed under Needs your decision for a human to confirm.

How many changes should one AI SEO pass make?

Few. The PageSeeds weekly skill allows at most 5 created actions, 15 executions and 3 new articles per pass, and a new mode-executing pass is refused if the last one ran less than 5 days ago.

Does the agent edit my live site directly?

No. Writes happen in a separate git worktree and land as a pull request. Nothing reaches the live checkout until you merge it.

Does this only work with Claude Code?

No. The same skill file runs in Claude Code, Kimi or Grok. The limits live in the skill and the CLI, not in the model.

Want to run it on your own site? Install PageSeeds: the first weekly pass is free, and Claude Code runs the skill from your repo. More tools for this workflow are in the SEO tools hub.