SEO Rank Watch: an agent skill that improves one keyword a week until it ranks #1

Skill: SEO Rank Watch
Continuously improve the Google rankings of the target site ({site}).

Goal: find a keyword that could reach #1, make ONE improvement that answers the search need, observe for 7 days. Repeat until #1.

Data
- data/seo/watchwords.json — keywords / target pages / priority
- data/seo/rank-history.json — rank history, append-only
- data/seo/improvement-log.json — improvement history / status / next review date

status:
- active — candidate for improvement
- observing — 7-day observation after an improvement
- achieved — reached #1; monitor only

Workflow
1. Measure rankings
Use Google Search Console by default:
  node {rank_script} --repo {repo_path} --append
Fetch average position, impressions and clicks from GSC and compare with the previous run.
Use WebSearch only when GSC is unavailable or you need today's position; WebSearch positions are approximate — GSC is the source of truth.
rank: null with 0 impressions does not necessarily mean "not indexed"; confirm with WebSearch if needed.

2. Review improvements older than 7 days
Check keywords with nextReviewDate <= today. Judge effect with 7-day GSC data, not the 28-day average:
  node {rank_script} --repo {repo_path} --days 7
- #1 → achieved
- improved but not #1 → active
- no effect → active; next time use a different improvement method
Record the verdict in improvement-log.json.

3. Pick ONE keyword to improve today
Exclude observing and achieved. Choose exactly one, in this order:
- rank 2–10 with impressions — prefer the one closest to #1
- rank 11–20 with high impressions
- improved-but-not-#1 / no-effect
- high-priority rank: null
- promising unregistered queries found in GSC
If there is no candidate, finish with the rank check and report only. Never invent a target just to have something to improve.

4. Analyze the search need
Before improving, always: define in 1–2 sentences who is searching and what they want to know; check the current top 1–3 pages with WebSearch; compare them with the target page; identify what is missing as a gap.
Do not add text for SEO's sake — add the information the searcher wants.

5. Improve ONE keyword
Implement only what the gap requires, e.g. title / description / intro / FAQ; missing content; internal links between article ↔ area page ↔ detail page; missing real data.
Internal links exist to lead the searcher to what they want next, not only for SEO.
Improve exactly one keyword per run. Never apply noindex changes or large structural changes on your own — propose and get approval.

6. Record and wait 7 days
Write to improvement-log.json:
{ "keyword": "...", "targetPath": "...", "status": "observing", "nextReviewDate": "today+7d",
  "actions": [{ "date": "...", "rankAtAction": 4.2, "needs": "search need", "done": "what was actually changed" }] }
Commit changes to data/seo/*.json to Git. Never re-improve an observing keyword before nextReviewDate.

Report
Finish with a short report: keywords that rose/fell markedly since last time; today's effect verdicts; the keyword chosen and why; the inferred search need; what was changed; keywords under observation with nextReviewDate.
Never assert that rankings will improve. Report what changed; judge effect by the next measurement.

Guardrails
- Do not scrape Google SERPs with custom scripts; use GSC or WebSearch
- One keyword per run
- Respect the 7-day observing cooldown
- Never rewrite past data in rank-history.json
- Never print or commit credentials or secrets
- No noindex or large structural changes without approval
- Never assert improvement effects
- If there is nothing to improve, do nothing

"Measure → pick one near-#1 keyword → study intent → improve → observe 7 days → judge by measurement." Repeat until #1.