wp-site-health-auditor – Coding skill for AI agents

WP Site Health Auditor

When to Use This Skill

• The user pastes a WordPress Site Health report (Tools > Site Health), as text or screenshot
• The user pastes raw Site Health debug info (Tools > Site Health > Info) and asks what's wrong
• The user mentions "site health", "recommended improvements," or "critical issues" for a WordPress site
• The user asks to clean up, harden, or speed up a WP install based on that screen

Turns a WordPress Site Health report (Critical issues / Recommended improvements / Passed tests) into a

prioritized, risk-tiered fix plan — then executes the safe fixes and hands off the rest with exact

commands or code.

⚠️ Safety — read before touching any file

This skill edits wp-config.php, .htaccess, and php.ini-equivalent settings, and deletes plugins and

themes. All three are one bad edit away from a white-screen-of-death or a broken upload path. **Never skip

this section, even for a one-line change, even if the user is in a hurry.**

Before any edit or deletion, in this order:

1. Back up the specific file(s) you're about to touch outside the web root, not just "have a backup somewhere":

   umask 077
   backup_dir="../wp-site-health-backups/$(date +%Y%m%d-%H%M%S)"
   mkdir -p "$backup_dir"
   cp -p wp-config.php "$backup_dir/wp-config.php"
   cp -p .htaccess "$backup_dir/.htaccess"
   

If shell access isn't available, tell the user to download the current file via SFTP/host file

manager first, and don't proceed until they confirm they have it.

2. Confirm a full site/database backup exists before deleting any plugin or theme, or running

wp search-replace. If the user doesn't have one and has a backup plugin active (UpdraftPlus, etc.),

trigger a backup first: wp help updraftplus # verify installed plugin command before invoking a backup or the plugin's own WP-CLI command, or tell them to

click "Backup Now" and wait for confirmation before continuing.

3. Never run wp search-replace without --dry-run first, and always show the dry-run output to the

user before running it for real. This command rewrites the database in place — a wrong pattern can

corrupt serialized data across every table it touches.

4. After any PHP file edit, lint it before reloading the site:

   php -l wp-config.php
   

For .htaccess changes, run apachectl configtest if available, or check the site immediately.

A syntax error in wp-config.php takes the entire site down immediately. Do not skip the lint check to

save a step.

5. Change one thing at a time, then verify the site still loads (homepage + wp-admin) before making

the next change. Don't batch multiple Tier 2 file edits into one pass — if something breaks, you want to

know which change did it.

6. Give the user the exact rollback command alongside every edit:

   cp ../wp-site-health-backups/<timestamp>/wp-config.php wp-config.php
   

State this even if nothing goes wrong — it costs one line and saves a panicked user later.

If the user says "just do it, skip the backup" — still create the backup silently as part of the edit

sequence and tell them you did. Refuse to skip step 1 or step 4 entirely; those two are non-negotiable

regardless of urgency, since the failure mode (corrupted wp-config.php, dead site) is worse than the ten

seconds a backup costs.

Overview

The Site Health screen is diagnostic, not prescriptive. It tells the site owner *that* something is wrong

(e.g. "you should use a persistent object cache") but not *how* to fix it, and it mixes items that are

one-click-safe (deactivate a plugin) with items that require host-level changes (php.ini, object cache

backend) or are purely informational (SQL server version — no action needed). This skill sorts that out —

safely.

Phase 1 — Parse the report

Input is usually one of:

• Pasted plain text copied from Tools > Site Health (Status tab)
• Pasted plain text from Tools > Site Health > Info (the debug data export)
• A screenshot of the Status tab
• WP-CLI output (wp site-health check is not a core command; note that up front, don't invent one — see Phase 4)

Extract three buckets exactly as WordPress labels them:

1. Critical issues (red) — always fix first, always confirm before touching.

2. Recommended improvements (yellow) — the bulk of real work; triage by risk tier below.

3. Passed tests (green) — skip. Do not "fix" or re-verify passed tests unless the user asks. Do not

invent problems with green items — a common failure mode is treating "SQL server is up to date" as

something to act on. It isn't.

If the report is a screenshot, transcribe item titles + category tags (Security/Performance/SEO/Privacy)

verbatim before triaging — don't paraphrase the WordPress-generated title, it's used for the fix lookup in

Phase 3.

If no report was pasted and the user just says "audit my site health," ask them to paste the Status tab

text (fastest) rather than guessing — Site Health results are host- and config-specific and guessing wastes

a turn.

Phase 2 — Risk-tiered triage

Classify every non-passed item into one of three tiers before touching anything. Present this triage table

to the user first for anything above Tier 1 count of 3+ items — don't silently start deactivating plugins.

Tier 1 — Safe, reversible, auto-fixable in wp-admin or via WP-CLI

Assess actual state: plugin/theme deletion, indexing and config changes can cause data loss, exposure or downtime. Still back up per the Safety section before deleting

anything. Fix directly once the user confirms the item list.

• Remove inactive plugins/themes (they aren't running, deactivation already happened — this is just

deletion of dead code)

• Turn off WP_DEBUG display in production (WP_DEBUG_DISPLAY, not WP_DEBUG itself if the user still

wants logging)

• Enable search engine indexing / fix robots visibility toggle
• Update the site tagline off "Just another WordPress site"

Tier 2 — Requires host/server-level access — Claude drafts the change, user or host applies it

Cannot be fixed purely from wp-admin; needs php.ini, .htaccess, wp-config.php, or hosting panel access.

Draft the exact snippet, explain where it goes, remind the user of the backup + lint steps above, and flag

that a server restart or host support ticket may be needed.

• Permalink structure change (migration — existing URLs break without redirects; require a redirect plan and CDN/cache flush before applying)
• post_max_size < upload_max_filesize mismatch
• Persistent object cache not available (Redis/Memcached)
• Page cache not detected
• PHP version/module changes
• HTTPS/SSL configuration
• Loopback/REST API failures caused by firewall or security plugin blocking

Tier 3 — Informational / host-dependent, no fix exists or none needed

Report as informational only. Do not attempt a fix, do not suggest one unless directly asked.

• SQL server version notices when already current
• "Autoloaded options are acceptable" type passed-adjacent info
• Anything already green in Passed tests

Phase 3 — Fix recipes by item

Match the WordPress-generated item title (case-insensitive substring match is fine) to a recipe below.

Every recipe below assumes the Safety section has already been followed for that file. If an item doesn't

match anything here, say so explicitly rather than fabricating a fix — Site Health's item set changes

across WP core versions and this list isn't exhaustive (see references/catalog.md for the fuller list

including rarer items).

You should remove inactive plugins / themes — Tier 1

# confirm full site backup exists first (Safety step 2)
wp plugin list --status=inactive --field=name
wp plugin delete <plugin-slug>

wp theme list --status=inactive --field=name
wp theme delete <theme-slug>

Never delete the currently active theme's parent if the active theme is a child theme. Never delete

Twenty Twenty-Five (or the current default core theme) if it's the only fallback theme — WordPress needs

at least one broken-theme fallback; recommend keeping one bundled default even if inactive.

Confirm the exact plugin/theme names with the user before deleting — inactive isn't the same as unused;

some plugins are intentionally kept inactive as a staged rollback.

post_max_size smaller than upload_max_filesize — Tier 2

This breaks large file uploads (post data gets truncated before the file size limit is even reached).

Fix by raising post_max_size to be >= upload_max_filesize, typically with headroom for form overhead.

Where to set it (pick whichever the host supports, in this order of preference):

1. Host control panel PHP settings (cPanel "Select PHP Version" > Options, Plesk, etc.) — no code needed,

safest option, skip the file-backup steps entirely.

2. php.ini (if the user has server access) — back up first (cp php.ini php.ini.bak-<timestamp>):

   upload_max_filesize = 64M
   post_max_size 

… (full content is in the download package)