WordPress SEO cleanup with an AI agent

By Andrew Ivanov · Last updated

What does this skill do?

The seo-cleanup skill is a SKILL.md file that teaches an AI agent a safe routine for tidying on-page WordPress SEO — audit titles, slugs, excerpts, and internal links, then fix the on-page fields behind a database checkpoint, being careful with slugs because this toolset has no redirect tool. You install it once and ask for an SEO cleanup when a section of the site needs its metadata brought into line.

Most on-page SEO problems are unglamorous: a page with no meta description, a title that repeats another page's, a slug like ?p=482 that never got fixed, or internal links still pointing at an old URL. This skill walks the library, reads each page's title, slug, and excerpt, and reports which ones are weak, missing, or duplicated. The audit steps are all read-only, so a full inventory of your metadata is safe to run anytime, on a live site, before a single field is edited.

When it does write, it stays on the levers that are genuinely under the toolset's control. The provider-independent SEO fields are the native post fields: the title becomes the page <title>, the slug becomes the URL, and the excerpt feeds the meta-description fallback and social snippet. The agent edits these one post at a time with the content MCP tool, changing only the fields you pass, all behind the checkpoint it took before starting. If Rank Math is active, its plain meta keys are writable too; if Yoast is active, its custom title and description live under protected keys the plugin will not write, so those stay a manual edit — and the skill tells you which case you are in rather than guessing.

The most important thing this skill is honest about is redirects: it cannot create them. There is no redirect tool in Cowboy MCP, so changing the slug of a published, indexed page will 404 the old URL with nothing to catch the traffic. The routine treats slugs as high-risk for exactly this reason. It proposes slug changes rather than firing them off, and after any change it uses a search-and-replace pass to repoint your internal links to the new URL — while reminding you to set up the actual redirect at your server or with a redirect plugin. Cleanup that would quietly break live URLs is flagged and left for you to decide.

Which Cowboy MCP tools does it use?

The cleanup audits with read-only tools, then edits on-page fields with two write tools behind a checkpoint. It also detects which SEO plugin is active so it knows how metadata is stored. Every tool below is a real Cowboy MCP tool the agent sees over MCP.

Tool What it does
wp_seo_get_provider Detects whether Yoast SEO or Rank Math is active — decides how meta fields are stored
wp_list_posts · wp_get_post Inventory posts and pages, then read one page's title, slug, excerpt, and meta
wp_get_rewrite_rules Inspects permalink rules and tests a URL path, so you see what a slug change would break
wp_db_health_report Read-only check for revision bloat, auto-drafts, and orphaned postmeta
wp_create_checkpoint · wp_list_checkpoints Snapshots the database and confirms it before any edit
wp_update_post Sets a better title, excerpt, or slug (and Rank Math meta) one post at a time
wp_search_replace Repoints internal links after a slug change — defaults to dry_run: true for a safe preview
wp_undo_change Reverts a single edit from the undo journal without a full restore

How do I run it?

Once the skill is installed you run it in plain English, and the agent picks up the SKILL.md and follows its steps. Because the routine names its own tools, a short request is enough, and you can scope it from a full audit down to one fix or a report-only pass. Three prompts that work:

The first prompt is a pure audit. The second scopes writes to safe fields and explicitly protects slugs. The third takes on a risky slug change deliberately, with the internal-link repair and the redirect reminder built in. In every case safe mode applies, a dry run previews each write, and the checkpoint makes the whole pass reversible.

How do I install the skill?

A skill is just a folder with a SKILL.md file inside it. Download this skill's file and drop it into your agent's skills directory — no build step, no dependencies. Where it goes depends on whether you want it in one project or everywhere:

Keep the folder name (wordpress-seo-cleanup) matching the name field in the file's frontmatter. After the file is in place, start a new session and ask your agent for an SEO cleanup — it will find the skill by its description. The full file is below for reference; the download link above serves this exact text.

---
name: wordpress-seo-cleanup
description: Use when asked to clean up on-page SEO for a WordPress site connected via Cowboy MCP — audits titles, slugs, excerpts, and internal links, then fixes them behind a checkpoint. Notes it cannot create redirects.
---

# WordPress SEO cleanup

Tidy the on-page SEO of a WordPress site through Cowboy MCP: audit titles, slugs, excerpts, and internal links, then fix them safely. Read first, checkpoint before any edit, and be careful with slugs — this toolset has no redirect tool, so a changed URL is a changed URL.

## Before you start

1. Detect the SEO plugin: call `wp_seo_get_provider` (Yoast, Rank Math, or none). This decides how meta titles and descriptions are stored (see Notes).
2. Confirm the connection with `wp_site_info` and review the permalink structure it reports.
3. Create a database checkpoint with `wp_create_checkpoint` (label it "seo-cleanup") and confirm it with `wp_list_checkpoints` before editing.

## Steps

1. **Audit content (read-only).** Call `wp_list_posts` to inventory posts and pages, flagging missing excerpts, weak or duplicate titles, and non-descriptive slugs. Use `wp_get_post` to read a page's title, slug, excerpt, and meta.
2. **Audit rewrite rules (read-only).** Call `wp_get_rewrite_rules` to review the permalink rules and test specific URL paths, so you understand what a slug change would break.
3. **Database hygiene (read-only).** Call `wp_db_health_report` for revision bloat, auto-drafts, and orphaned postmeta worth cleaning.
4. **Fix on-page fields.** Call `wp_update_post` for one post at a time to set a better `title`, `excerpt`, or `slug`. Title and excerpt are safe; treat `slug` as high-risk (step 6).
5. **Fix plugin SEO meta (Rank Math only).** If Rank Math is active, its meta keys (`rank_math_title`, `rank_math_description`) are plain and writable via `wp_update_post`'s `meta` object. Yoast stores these under underscore-protected keys MCP will not write — set those in the Yoast interface.
6. **Repoint internal links after a slug change.** Changing a published slug 404s the old URL, and there is no redirect tool here. After any slug change, call `wp_search_replace` (it defaults to `dry_run: true`) to update internal links pointing at the old URL, and set up a redirect at the server or with a redirect plugin yourself.

## Notes

- The provider-independent SEO levers are the native post fields: `title` (the page `<title>`), `slug` (the URL), and `excerpt` (the meta-description fallback and social snippet). Prefer these.
- No redirect tool exists in this toolset. Never bulk-change slugs on indexed URLs expecting redirects to appear — they will not.
- `wp_search_replace` is destructive; keep `dry_run: true` for the preview, review the match count, then run it again with `dry_run: false`.
- Undo one edit with `wp_undo_change`; restore the whole session with `wp_restore_checkpoint`.

## Report format

Summarize back to the site owner:
- Titles, excerpts, and slugs changed, each old to new, with slug changes called out separately.
- Rank Math meta updated, or a note that Yoast meta needs the plugin interface.
- Any internal-link search-replace run, with the match count.
- Slugs you did NOT change because they would break live URLs without a redirect.
- The checkpoint id for a full rollback via `wp_restore_checkpoint`.