Documentation » Playbook: Weekly SEO Plan

Weekly SEO plan: a routine for the AI agent

If you are a person reading this: this page is written for your AI agent. Once a week, paste this line into Claude, ChatGPT or any MCP client:

Read https://kafkai.com/docs/weekly-seo-plan.md and run it on my site.

There are two other ways to start it:

  • As a prompt. If your client lists the prompts of the Kafkai connection, choose kafkai_weekly_seo_plan.
  • As a skill. If your client supports skills, install the skill file once, then ask for "my weekly SEO plan".

The rest of this page is for the agent.

Your job

A Kafkai customer asked for their weekly SEO plan. Read the data Kafkai holds for their project, then give three actions for this week, in order. Reply in the language the customer writes in. Ask one question at a time.

If you have no tools whose names start with kafkai_, go to Without Kafkai.

Before you start

  1. Call kafkai_list_projects (free). If there is more than one project, ask which one. If there is none, send the customer to https://kafkai.com/docs/onboarding.md and stop.
  2. Call kafkai_get_project_summary (free). Read last_research, the competitor list, backlinks and search_console.status.
  3. If last_research.status is pending, research is still running. Say so and stop. Run the plan when it has finished.
  4. Check the age of the data. Rankings, keywords and backlinks are as old as the last full research run: last_research.completed_at when last_research.kind is update and last_research.status is success. If the last run is failed or partial, or its kind is competitor_add, that date is not the date of the stored data: tell the customer the data may be older. If that date is more than 30 days ago, tell the customer the date and offer an update. An update costs 500 credits for the site plus 350 credits for each competitor. State the total for this project. Never call kafkai_update_keywords before the customer agrees to that total. If the customer says no, continue with the stored data.
  5. Ask which keywords to watch on page one: at most 5, and the same ones every week. If the customer has no list, run Step 2 after Step 3: propose 5 from the results of Steps 1 and 3, and ask the customer to confirm them before you call kafkai_check_search_results.
  6. State the cost and wait for a yes. When every step runs, the plan costs about 43 credits. Leave out the steps you will skip. Call kafkai_get_credit_balance (free). If the balance is too low, point to https://kafkai.com/en/pricing/ and stop.

The steps

Each step says what it costs and when to skip it. For a skipped step, write one line in the report: what was skipped and how to turn it on.

Step 1: What changed in the rankings?

Run this step only when a full research run finished in the last 7 days. Without a new run the answer is the same as last week: skip it and give the date of the data.

Call kafkai_get_ranking_changes with days=7 and limit=20. Read the summary first, then the biggest moves. For each important move, say what the likely reason is, and say when it is a guess.

Cost: about 4 credits.

Step 2: Who is on page one?

Call kafkai_check_search_results with the keywords from "Before you start". Kafkai fetches each page fresh, so this step is new every week. Report where the customer's site is, and read changes: who entered, who left, who moved. changes is null on the first check of a keyword. A null domain means "unknown", not "absent".

Cost: 1 credit per call plus 5 credits per keyword fetched fresh. With 5 keywords: at most 26 credits.

Step 3: What to write next?

Call kafkai_get_catchup_keywords with limit=20: keywords competitors rank for and the customer does not. Skip this call when the project has no competitor. Then call kafkai_get_complement_keywords with limit=20: related keywords nobody in the project targets yet.

Pick at most three keywords to write about next. Prefer high search volume with low difficulty. Leave out keywords the customer has already written about. Ask if you do not know.

Cost: about 6 credits.

Run this step only when a full research run or a backlink update finished in the last 7 days. Otherwise skip it and give the date of the data. Never call kafkai_update_backlinks unless the customer asks and agrees to its price.

Call kafkai_get_backlink_changes with competitor_domain="all" and days=7. Read gains and losses from period_totals. Do not subtract one total from another. Then call kafkai_get_link_gaps with limit=20: sites that link to two or more competitors but not to the customer. Name at most three sites worth contacting.

Cost: about 4 credits.

Step 5: What to fix first? (Search Console)

Run this step only when search_console.status is ready. Otherwise skip it and point to https://kafkai.com/en/docs/google-search-console/.

Call kafkai_update_search_console (free, at most one fetch a day). If it queued a fetch, wait about a minute. Then call kafkai_get_search_console_insights with limit=5. The limit applies to each kind of flag. Start with striking_distance and ctr_gap: they are the fastest wins.

Cost: about 3 credits.

Step 6: The report

Write a short report in this order:

  1. Three actions for this week, most important first. For each: what to do, on which page or keyword, and the number that supports it.
  2. What changed: rankings, page one, links. One or two lines each.
  3. Skipped steps, one line each, with how to turn each one on.
  4. Data dates and cost: the date of the last research run, and the credits this run used (each response reports them in _usage or billing).

Offer to write the first action's article or page change. Do not start it unasked.

Without Kafkai

Steps 2, 5 and 6 work without Kafkai, with more manual work:

  • Step 2: search the web for each keyword and list the sites on page one. Keep the list, so next week you can compare.
  • Step 5: ask the customer for a Search Console export of queries for the last 28 days and the 28 days before. Look for queries at positions 8 to 20 and for queries with many impressions and few clicks.
  • Step 6: write the report from what you have.

Steps 1, 3 and 4 need Kafkai's stored data. To connect Kafkai, read https://kafkai.com/docs/onboarding.md. To find a site's competitors for free, use https://kafkai.com/en/find-competitors/.

Rules

  • Say the credit cost before every call that spends credits, and wait for the customer to agree.
  • Read stored data only. A research update is the customer's decision.
  • Skip a step whose data source is not connected. Never report a missing source as "no data".
  • Quote every number with its date.
  • Never ask the customer to paste a password or an API token into this conversation.
  • If a tool returns an error, show the customer the message and point to https://kafkai.com/en/docs/troubleshooting/.