How to Use WP Debug Toolkit with AI Coding Assistants

Install the WP Debug Toolkit (WPDT) skill by running npx skills add WP-Debug-Toolkit/wpdt-cli from your project directory. This gives AI coding assistants, including Claude Code, Cursor, Codex, Gemini CLI, Windsurf, and GitHub Copilot, the ability to profile REST API endpoints, discover and annotate routes, manage debug settings, and analyze database queries via natural conversation, without needing you to configure anything extra.

Installing the Skill

Step 1: Install the WPDT CLI Skill

Run the install command from your project’s root directory, the same location where your agent already operates:

bash

# Run from your project directory

npx skills add WP-Debug-Toolkit/wpdt-cli

This single command installs three things:

Agent instructions: A SKILL.md file describing which wp dbtk commands exist and when to use each one
A wrapper script: A small executable that handles WP-CLI environment detection for you
Reference docs: Additional documentation your agent loads on demand for specific tasks

Once installed, you do not need to configure anything else in addition. Your AI coding assistant reads the skill automatically the next time a relevant question or task comes up. You do not need to tell it which commands to run or how to invoke WP-CLI.

Quick Examples

Once the skill is installed, your agent translates plain requests into the correct wp dbtk commands and runs them for you. This makes it easy so that even if you do not know any CLI syntax, you can still get started:

“Profile the WooCommerce products endpoint and tell me if there are duplicate queries.”
“What REST API endpoints are available on this site?”
“Give me a brief of the WooCommerce REST API so you know what’s there.”
“Enable WordPress debug mode.”
“Show me the parameters for the orders endpoint.”
“Save a note that POST /wc/v3/orders creates an order and requires shop_manager.”
“Turn everything off and clean up the logs.”

Advanced Workflows

Compare Query Performance Before and After a Code Change

This workflow uses iterative profiling to measure the database impact of a code change in real time.

You: “Profile /wc/v3/products and show me the queries it runs.”

Your agent runs:

bash

wp dbtk api call GET /wc/v3/products --profile=queries

It reports back the query count, total time, and any slow or duplicate queries it found.

You: Edit your code yourself (for example, add a transient cache around a product lookup). Once that’s done, ask the agent to: “Profile that endpoint again and compare it to the last run.”

Your agent runs the same command a second time and compares the new query count and timing against the first result, telling you whether the change reduced database load.

For full details on what each profiling mode captures, see Profiling Endpoint Performance.

Annotate Endpoints for Future Sessions

After your agent investigates an endpoint, you can ask it to record what it learned so future sessions don’t have to rediscover it.

You: “That /wc/v3/orders POST endpoint creates a new order and writes to the database. Annotate it so we remember that, and flag it as something that needs confirmation before calling.”

Your agent runs:

bash

wp dbtk api edit /wc/v3/orders --method=POST \

  --description="Creates a new WooCommerce order" \

  --safety=mutates-data \

  --verification=verified-runtime

This annotation persists across discovery runs. The next time you or your agent run wp dbtk api discover, wp dbtk api list, wp dbtk api show, or wp dbtk api search, this endpoint shows up with its description and safety level already attached, eliminating the need for any rediscovery.

For the full --safety and --verification classification system, see Annotating Routes with Custom Metadata.

What Happens Behind the Scenes

When you make a request, your AI coding assistant follows the same four-step flow every time:

The agent reads SKILL.md to understand which wp dbtk commands are available and when to use them.
The agent uses the wrapper script to invoke WP-CLI with the correct PHP binary and database socket for your environment.
The agent runs the actual wp dbtk command through the wrapper.
The agent parses the JSON output and explains the results in plain language.

You’ll see the command in your agent’s tool output. When you run a command with –profile, the response includes both the API data and the performance profile; otherwise, it includes only the API data.

Why the Wrapper Script Exists

AI agents run in a regular terminal session, not inside a site-specific shell like Local by Flywheel’s. That means they often lack access to the correct PHP binary or MySQL socket for your site. The wrapper script, installed at .agents/skills/wpdt-cli/scripts/wp, detects your environment and automatically constructs the correct WP-CLI invocation. It currently supports Local by Flywheel and standard WP-CLI installations. For the underlying detection logic and manual configuration options, see CLI Environment Setup.

Common Issues and How to Fix Them

“wp Is Not Found” or Gets a Database Error

Likely cause: The wrapper script could not automatically detect your local environment.

Fix: Run bash .agents/skills/wpdt-cli/scripts/wp --probe to see what environment the wrapper detected. If it doesn’t match your setup, follow the manual configuration steps in CLI Environment Setup.

Agent Doesn’t Seem to Know About WPDT Commands

Likely cause: The skill wasn’t installed in the current project, or your agent’s session started before installation.

Fix: Re-run npx skills add WP-Debug-Toolkit/wpdt-cli from your project directory, then start a new agent session.

Agent Runs Commands but Gets 401 or 403 Permission Errors

Likely cause: WP-CLI commands run with no authenticated user by default, so any endpoint requiring specific capabilities rejects the request until you specify which WordPress user to run as.

Fix: Ask your agent to add --user=1 (or the relevant admin user ID) to the command. This tells WP-CLI which WordPress user identity to assume, so the endpoint’s permission checks evaluate against that user’s capabilities.

Profiling Shows Zero Queries

Likely cause: The endpoint returned a cached response, or the request genuinely triggers no database queries.

Fix: Try a different endpoint, or ask your agent to force a fresh lookup by adding query parameters that bypass caching.

“wp dbtk api bootstrap Says ‘Source Not Found'”

Likely cause: The schema store hasn’t been populated for that source yet.

Fix: Run wp dbtk api discover first. This populates the schema store that bootstrap, export, and list --annotated-only all read from.

Frequently Asked Questions

Which AI Coding Assistants Work with the WP Debug Toolkit CLI Skill?

WP Debug Toolkit’s CLI skill works with Claude Code, Cursor, VS Code Copilot, Codex, Gemini CLI, Windsurf, and any agent that supports the open Agent Skills standard for .agents/skills/ directories. Compatibility comes from following that shared convention, not from a WPDT-specific integration with each tool.

Can My AI Agent Accidentally Make Destructive Changes to My WordPress Site Using These Commands?

Your agent is instructed to treat endpoints annotated --safety=mutates-data or --safety=destructive as requiring your explicit confirmation before calling them. However, wp dbtk api call makes a real request with no separate dry-run mode for arbitrary endpoints. The --dry-run flag exists only for wp dbtk api import, which applies to annotation packs, not live API calls. You’d want to be deliberate about asking your agent to call an endpoint annotated as destructive.