agent-skills/skills/seo-change-lifecycle/SKILL.md

name, description, license, source

name	description	license	source
seo-change-lifecycle	Use when auditing a content site's SEO, proposing metadata changes, or evaluating whether an applied SEO change helped. Treat findings as measured conditions and close the loop through approval, delivered-output verification, and delayed Search Console comparison.	MIT	adapted from https://github.com/citeworthyio/seo-agent/blob/b78bb487f2819c3c7cc2ba6f3f5626ea0b841840/README.md (How it works, Findings lifecycle, Analytics)

SEO Change Lifecycle

An SEO edit is not complete when source content changes. It is complete only after the served page is recrawled and the outcome has had time to emerge in search data. Use this loop for metadata and technical on-page changes.

1. Snapshot what crawlers actually receive

Start from the sitemap and fetch every listed final URL. Record the delivered status, title, meta description, canonical, robots directive, OpenGraph image, and JSON-LD types. Do not audit templates or CMS fields in place of the response: an edge rewrite, stale cache, redirect, or failed deployment can make the served page disagree with its source.

If no usable sitemap exists, use a bounded, same-origin link crawl and label the result incomplete. A link crawl cannot find orphan pages, so absence from that sample is not evidence that a page does not exist.

2. Diagnose deterministic conditions

Prefer repeatable rules whose evidence can be preserved and checked again. At a minimum, inspect:

• sitemap URLs returning errors or redirects;
• missing titles, duplicate titles, and titles whose core exceeds 60 characters or whose delivered total exceeds 80;
• missing descriptions, descriptions shorter than 70 or longer than 160 characters, and descriptions ending in ... because upstream truncation can hide an over-long source value;
• missing or off-page canonicals;
• noindex pages still present in the sitemap;
• missing og:image and missing Article JSON-LD on known article routes.

Decode HTML entities before length checks so & counts as the one character a reader sees. Key each finding by (path, rule): keep it open while the condition persists and auto-resolve it only when a fresh crawl no longer reproduces it. This makes findings sensors, not tickets someone can close without fixing the underlying page.

3. Draft a constrained proposal

Give a drafter the page's observed content, the exact failed rule, the current served value, and the site's positive style guidance. Require the smallest field change that can clear the finding. Use deterministic surgery when there is one right answer (for example, removing a duplicated brand suffix or replacing a canonical with the page's own normalized URL); a model adds risk without value.

Validate model output outside the model. Reject an unchanged value, forbidden terms, a title that includes a suffix the publishing layer will append, or copy outside the agreed length and sentence constraints. An invalid proposal is no proposal, not a reason to relax the gate.

4. Review, apply, journal, and recrawl

Require human approval by default. Record the old value, approved value, field, path, timestamp, and a reversible change identifier. After applying, fetch the public URL again and compare the delivered field with the approved value. Keep the finding in an applied, awaiting recrawl state until that comparison passes.

This extra verification catches the failures source inspection misses: a wrong cache key, route gap, stale CDN response, lost edge binding, or deployment that never reached the serving path. A successful write to a CMS or override store is not proof that crawlers see the change.

5. Measure impact without claiming causation

Use page-level Search Console data, not site-wide totals. Leave a three-day settling gap after the change, then compare equal 14-day before/after windows; repeat with 28-day windows when enough data exists. Compare clicks and impressions as per-day rates and CTR/position as impression-weighted averages. Do not calculate a verdict if either window is absent or the two windows total fewer than 50 impressions.

Treat a relative CTR movement of about 15% or an average-position movement of about 1.0 as a review signal, with impression shifts checked for confounding. Call the result correlation, never causation: seasonality, algorithm changes, competitors, and query-mix changes remain plausible explanations. A negative signal should open a review/revert decision, not trigger an automatic rollback.