Index of every page on this site: llms.txt
All skills
wordpress avatar

/wp-performance

@7374e6f official
by wordpresswordpress/agent-skills2.4k stars
351
Run it yourself

Use when investigating or improving WordPress performance (backend-only agent): profiling and measurement (WP-CLI profile/doctor, Server-Timing, Query Monitor via REST headers), database/query optimization, autoloaded options, object caching, cron, HTTP API calls, and safe verification.

Use this Skill: https://skilld.dev/gh/wordpress/agent-skills/wp-performance

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈76 tokens for metadata: the name and description. ≈1.4k when used: this file. ≈1.9k more on demand in 10 files.

Description uses 3.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈304 characters, or 3.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

WP Performance (backend-only)

When to use

Use this skill when:

  • a WordPress site/page/endpoint is slow (frontend TTFB, admin, REST, WP-Cron)
  • you need a profiling plan and tooling recommendations (WP-CLI profile/doctor, Query Monitor, Xdebug/XHProf, APMs)
  • you’re optimizing DB queries, autoloaded options, object caching, cron tasks, or remote HTTP calls

This skill assumes the agent cannot use a browser UI. Prefer WP-CLI, logs, and HTTP requests.

Inputs required

  • Environment and safety: dev/staging/prod, any restrictions (no writes, no plugin installs).
  • How to target the install:
    • WP root --path=<path>
    • (multisite/site targeting) --url=<url>
  • The performance symptom and scope:
    • which URL/REST route/admin screen
    • when it happens (always vs sporadic; logged-in vs logged-out)

Procedure

0) Guardrails: measure first, avoid risky ops

  1. Confirm whether you may run write operations (plugin installs, config changes, cache flush).
  2. Pick a reproducible target (URL or REST route) and capture a baseline:
    • TTFB/time with curl if possible
    • WP-CLI profiling if available

Read:

  • references/measurement.md

1) Generate a backend-only performance report (deterministic)

Run:

  • node skills/wp-performance/scripts/perf_inspect.mjs --path=<path> [--url=<url>]

This detects:

  • WP-CLI availability and core version
  • whether wp doctor / wp profile are available
  • autoloaded options size (if possible)
  • object-cache drop-in presence

2) Fast wins: run diagnostics before deep profiling

If you have WP-CLI access, prefer:

  • wp doctor check --all (add --spotlight to show only warnings and errors)
  • or name the checks for a perf-focused run: wp doctor check autoload-options-size constant-savequeries-falsy constant-wp-debug-falsy

wp doctor check with no check names and no --all exits with an error instead of running anything.

It catches common production foot-guns (autoload bloat, SAVEQUERIES/WP_DEBUG, plugin counts, updates).

Read:

  • references/wp-cli-doctor.md

3) Deep profiling (no browser required)

Preferred order:

  1. wp profile stage to see where time goes (bootstrap/main_query/template).
  2. wp profile hook (optionally with --url=) to find slow hooks/callbacks.
  3. wp profile eval for targeted code paths.

Read:

  • references/wp-cli-profile.md

4) Query Monitor (backend-only usage)

Query Monitor is normally UI-driven, but it can be used headlessly via REST API response headers and _envelope responses:

  • Authenticate (nonce or Application Password).
  • Request REST responses and inspect headers (x-qm-*) and/or the qm property when using ?_envelope.

Read:

  • references/query-monitor-headless.md

5) Fix by category (choose the dominant bottleneck)

Use the profile output to pick one primary bottleneck category:

  • DB queries → reduce query count, fix N+1 patterns, improve indexes, avoid expensive meta queries.
    • references/database.md
  • Autoloaded options → identify the biggest autoloaded options and stop autoloading large blobs.
    • references/autoload-options.md
  • Object cache misses → introduce caching or fix cache key/group usage; add persistent object cache where appropriate.
    • references/object-cache.md
  • Remote HTTP calls → add timeouts, caching, batching; avoid calling remote APIs on every request.
    • references/http-api.md
  • Cron → reduce due-now spikes, de-duplicate events, move heavy tasks out of request paths.
    • references/cron.md

6) Verify (repeat the same measurement)

  • Re-run the same wp profile / wp doctor / REST request.
  • Confirm the performance delta and that behavior is unchanged.
  • If the fix is risky, ship behind a feature flag or staged rollout when possible.

WordPress 6.9 performance improvements

Be aware of these 6.9 changes when profiling:

On-demand CSS for classic themes:

  • Classic themes now get on-demand CSS loading (previously only block themes had this).
  • Reduces CSS payload by 30-65% by only loading styles for blocks actually used on the page.
  • If you're profiling a classic theme, this should already be helping.

Block themes with no render-blocking resources:

  • Block themes that don't define custom stylesheets (like Twenty Twenty-Three/Four) can now load with zero render-blocking CSS.
  • Styles come from global styles (theme.json) and separate block styles, all inlined.
  • This significantly improves LCP (Largest Contentful Paint).

Inline CSS limit increased:

  • The threshold for inlining small stylesheets has been raised, reducing render-blocking resources.

Reference: https://make.wordpress.org/core/2025/11/18/wordpress-6-9-frontend-performance-field-guide/

Verification

  • Baseline vs after numbers are captured (same environment, same URL/route).
  • wp doctor check --all is clean (or improved) when applicable.
  • No new PHP errors or warnings in logs.
  • No cache flush is required for correctness (cache flush should be last resort).

Failure modes / debugging

  • “No change” after code changes:
    • you measured a different URL/site (--url mismatch), caches masked results, or opcode cache is stale
  • Profiling data is noisy:
    • eliminate background tasks, test with warmed caches, run multiple samples
  • SAVEQUERIES/Query Monitor causes overhead:
    • don’t run in production unless explicitly approved

Escalation

  • If this is production and you don’t have explicit approval, do not:
    • install plugins, enable SAVEQUERIES, run load tests, or flush caches during traffic
  • If you need system-level profiling (APM, PHP profiler extensions), coordinate with ops/hosting.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning1mo5 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill is a WordPress performance optimization toolkit that uses standard diagnostics via WP-CLI and Query Monitor. All analyzed operations are local to the environment and follow established developer best practices.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

  • Runlayer9mo

    12/12 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 7374e6f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 2 months ago
Other metadata
compatibility
Targets WordPress 7.0+ (PHP 7.4.0+). Backend-only agent; prefers WP-CLI (doctor/profile) when available.

README badge

README badge for wordpress/agent-skills/wp-performance

Diagnoses and optimizes WordPress backend performance using WP-CLI profiling, Query Monitor headless API, and targeted fixes for database queries, autoloaded options, object caching, cron tasks, and remote HTTP calls. Requires backend-only access (no browser UI) and targets WordPress 6.9+ with PHP 7.2.24+.

Generated from the current SKILL.md.

Does this skill work with frontend performance issues like Core Web Vitals?
No. This is a backend-only skill for server-side profiling and optimization. It targets TTFB, database queries, autoloaded options, and cron — not frontend rendering or asset delivery.
What WordPress versions does this support?
WordPress 6.9+ with PHP 7.2.24+. The skill is aware of WordPress 6.9 CSS loading improvements but does not support earlier versions.
Do I need WP-CLI installed to use this skill?
WP-CLI is preferred and enables the fastest diagnostics (wp doctor, wp profile), but the skill can work without it using HTTP requests and log inspection.
Can this skill modify the site or install plugins?
Only with explicit approval in the environment/safety input. The skill defaults to read-only operations and will not make writes without confirmation.
Does this work on multisite installs?
Yes. The skill accepts `--url` targeting to profile specific sites within a multisite network.

Generated from the current SKILL.md. These answers refresh after source changes.