Wp Plugin Research

WP Plugin Research

Automate screenshot capture of WordPress plugin UIs, generate annotated HTML galleries, and import to Figma for UX review.

Shared reference: Read shared/common-steps.md for permissions, shell variable rules, Figma MCP setup, gallery generation, Figma import, annotation reference, comparison gallery, and troubleshooting. This file covers only WP-plugin-specific steps.

Quick Reference

| Step | What | Key Decision | |------|------|-------------| | 0 | Permissions | Switch to auto mode | | 1 | Choose environment (local vs remote) | Determines WP-CLI availability | | 2 | Gather ALL user input in one interaction | Objective, plugins, annotations, Figma | | 3 | Clean slate — deactivate other plugins | Local only | | 4 | Login via agent-browser | Re-login before each plugin | | 5 | Discover pages → filter by objective → show user | Filtering happens before any screenshots | | 6 | Handle interruptions & blockers | First-run gates, wizards, banners | | 7 | Capture screenshots + journey notes | Deduplicate before dispatching reviewer | | 7a | Write review brief | One per plugin | | 7b | Dispatch ux-reviewer subagent(s) | Validate manifest counts after | | 7c | Dispatch ux-comparator subagent | Multi-plugin only | | 8 | Generate HTML gallery, verify, get approval | Start server once, keep alive | | 9 | Import to Figma | Optional | | 10 | Cleanup | Restore plugins, delete temp user, kill server |

BEFORE YOU START: Create Tasks

Use TaskCreate to create a task for each step. Mark each as in_progress when starting and completed when done. This prevents skipping steps.

Tasks to create:

1. "Step 0: Permissions check"
2. "Step 1: Choose environment"
3. "Step 2: Gather user input"
4. "Step 3: Clean slate — deactivate plugins"
5. "Step 4: Login via agent-browser"
6. "Step 5: Discover pages + filter"
7. "Step 6: Handle interruptions"
8. "Step 7: Capture screenshots + review"
9. "Step 8: Generate HTML gallery"
10. "Step 9: Import to Figma (optional)"
11. "Step 10: Cleanup"

Step 0: Permissions (DO THIS FIRST — MANDATORY)

Read shared/common-steps.md → "Permissions" and "No Shell Variables in Bash Commands" sections. Follow those instructions exactly. Recommend the user switch to auto mode before the command-heavy steps — this skill runs agent-browser, WP-CLI, the local gallery server, and Figma MCP calls.

Step 1: Choose Environment

Use AskUserQuestion to determine where the WordPress site lives. This is the first question — everything else depends on it.

> Where is the WordPress site you want to review?

Options:

1. Local site — "I have a local WordPress setup (Local by Flywheel, MAMP, Valet, Docker, etc.)"
2. Remote/QA site — "I have a live or staging site with a URL and credentials"

Path A: Local Site

Ask the user (can be combined with Step 2 questions):

> Local site details: > - Directory path? (e.g., /Users/jane/Local Sites/my-site or leave blank if current directory) > - Do you have admin credentials, or should I create a temporary user? > - "Here are my credentials: username / password" > - "Create a temporary user for me" (requires WP-CLI)

Then run prerequisites:

| Check | How | Fix | |-------|-----|-----| | agent-browser | which agent-browser | npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser | | Figma MCP | Check for mcp__figma__generate_figma_design in available tools | See shared/common-steps.md → "Figma MCP Setup" | | Working directory | Check for wp-config.php or app/public/wp-config.php in the given path | Ask user for correct path | | WP-CLI | See "WP-CLI Setup" section below | Only needed if creating temp user or managing plugins | | Site is running | curl -s -o /dev/null -w "%{http_code}" | User must start their local server |

WP-CLI Setup (Local Sites Only)

WP-CLI setup varies by environment. Detect and configure automatically:

Try direct WP-CLI first — works on most setups (Valet, Docker, standard):

wp option get siteurl --path=""

If this works, use wp directly for all commands.

If direct WP-CLI fails, detect the environment:

Local by Flywheel:

1. Read ~/Library/Application Support/Local/graphql-connection-info.json for auth token
2. Query Local's GraphQL API to find the site ID matching the path
3. Find PHP binary under ~/Library/Application Support/Local/lightning-services/
4. Find MySQL socket at ~/Library/Application Support/Local/run//mysql/mysqld.sock
5. WP-CLI command pattern: "" -d "mysqli.default_socket=" -d "memory_limit=512M" "" --path=""

MAMP:

• PHP at /Applications/MAMP/bin/php/phpX.X.X/bin/php
• MySQL socket at /Applications/MAMP/tmp/mysql/mysql.sock

If WP-CLI is not installed: Download the phar from https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar, make it executable, and move to ~/.local/bin/wp.

WP-CLI Wrapper Script (Local Sites Only)

After resolving the WP-CLI command (with PHP path, socket, etc.), write a wrapper script to avoid repeating 200+ character commands:

# Write wrapper script — always in working directory, never inside the screenshots folder
cat > ./wp-cli-local " -d "mysqli.default_socket=" -d "memory_limit=512M" "" "$@" --path=""
WRAPPER
chmod +x ./wp-cli-local

Test it: ./wp-cli-local option get siteurl. Use ./wp-cli-local for ALL subsequent WP-CLI commands.

Why this path: The wrapper lives at ./wp-cli-local in the working directory — never inside the screenshots folder and never at an absolute path. This ensures:

• The permission Bash(./wp-cli-local *) always matches regardless of where screenshots are saved
• No spaces in the path (avoids "backslash-escaped whitespace" warnings)
• Works even if the user specifies a custom screenshots directory like /Users/.../competitor-research

Discover Site URL (if user didn't provide one)

 option get siteurl --path=""

Create Automation User (if user chose this option)

 user create claude-reviewer claude@localhost.local --role=administrator --user_pass=claude-ux-review --path=""

Credentials: claude-reviewer / claude-ux-review. Clean up in Step 10.

Path B: Remote/QA Site

Ask the user (combine with Step 2 questions):

> Remote site details: > - Site URL? (e.g., https://qa.example.com) > - Admin credentials? (username and password) > - Is the login page at /wp-login.php or a custom URL?

No WP-CLI setup needed. For remote sites:

• Skip WP-CLI detection entirely
• Skip temp user creation (use their credentials)
• Skip plugin activation/deactivation (the site is already configured how they want it)
• Use agent-browser only for login, navigation, and screenshots
• Do NOT modify anything on the site (no plugin changes, no user creation, no settings changes)

Important for remote sites:

• The user's credentials may use 2FA, custom login pages, or SSO — be prepared to handle non-standard login flows via agent-browser
• Some pages may require specific roles/permissions — if a page is inaccessible, note it and move on
• Plugin list comes from the admin UI (Plugins page), not WP-CLI

Step 2: Gather Remaining User Input (Single Interaction)

Combine these with the environment questions from Step 1 whenever possible. The user should answer everything in one interaction, then walk away.

Question: Plugins to review

• For local sites with WP-CLI: auto-detect installed plugins, show as options
• For remote sites: ask the user which plugins to review (they know what's installed)
• Let the user type custom plugin names if not in the list
• For local sites: if a plugin isn't installed, offer to install it via WP-CLI

Question: Comparison (only if 2+ plugins selected)

• Ask: "Would you like a side-by-side comparison of these plugins?"
• Options: "Yes — include a comparison table" / "No — just individual reviews"
• If yes, a comparison gallery will be generated after individual reviews using the ux-comparator subagent

Question: Review objective

• Ask: "What's the objective for this review?"
• Options:
• General review — capture all screens, note what's working and what isn't (default)
• First-time user experience — "How quickly can a new user get started?" Focus on onboarding, empty states, discoverability, and first-run friction
• Upsell & monetization audit — Focus on upsell density, upgrade prompts, dark patterns, and free-vs-pro boundaries
• Specific objective — free text (e.g., "How easy is it to configure email settings?" or "Can a user set up their first event in under 2 minutes?")

The objective shapes what gets annotated. All annotations should be viewed through the lens of the chosen objective.

Question: Figma import

• Ask: "Do you have a Figma file URL for import?"
• Options: "Yes, I'll paste it" / "Skip Figma import"

Question: Annotation depth

• Ask: "How detailed should annotations be?"
• Options:
• None — screenshots only, no annotations (fastest)
• Light — brief colored callouts (positive/critical/observation) with 1-2 sentence descriptions
• Impact & Opportunity — each annotation scored on Impact (1-5) and Opportunity (1-5). Best for presenting findings to stakeholders.

After gathering input, print a summary:

> UX Review Plan: > - Plugin(s): WPForms, Sugar Calendar Bookings > - Objective: General review > - Comparison: Yes > - Annotations: Light > - Figma import: Yes (fileKey: XXXXX) > - Estimated screens: ~10-15 per plugin > > I'll now work through the review autonomously. I'll check in when the HTML gallery is ready for your approval before importing to Figma.

This lets the user walk away while work happens.

Step 3: Clean Slate (Local Sites Only)

Skip this step for remote/QA sites — do not modify plugins on remote sites.

For local sites, deactivate ALL other plugins so there are no cross-plugin notices, banners, or conflicts:

# List all active plugins except the target
 plugin list --status=active --field=name --path=""

# Deactivate all except target (use memory_limit to avoid Elementor OOM)
 plugin deactivate  --path=""

# Ensure target is active
 plugin activate  --path=""

Important: Always use -d "memory_limit=512M" with WP-CLI commands — plugins like Elementor and WooCommerce can exhaust the default 128M during deactivation.

Step 4: Login via agent-browser

Sessions expire frequently. Always re-login before each plugin.

Standard WordPress login (/wp-login.php):

agent-browser --session  open "/wp-login.php"
agent-browser --session  fill "#user_login" ""
agent-browser --session  fill "#user_pass" ""
agent-browser --session  click "#wp-submit"

For remote sites with custom login:

• If the user specified a custom login URL, use that instead of /wp-login.php
• If the login page looks different (custom theme, SSO redirect), use snapshot -i to find the correct form fields and submit button
• If 2FA is required, ask the user to provide the code via AskUserQuestion

Verify login succeeded — open the dashboard and check it loads:

agent-browser --session  open "/wp-admin/"

Step 5: Discover Plugin Pages

Do NOT hardcode menu URLs. After login, use snapshot to find the plugin's menu:

agent-browser --session  open "/wp-admin/"
agent-browser --session  snapshot -i 2>&1 | grep -i "plugin-keyword"

Click the main menu item, then snapshot again to find all sub-pages/tabs. See shared/common-steps.md → "agent-browser Click Syntax" for ref syntax rules.

Build a list of all pages/tabs to capture before starting screenshots. Example:

1. Events list (main page)
2. Add New Event
3. Calendars
4. Tickets
5. Venues
6. Settings (+ each settings tab)
7. Tools
8. Addons

Filter by Objective (Non-General Only)

Skip if the objective is "General review." Otherwise, review the page list and remove pages NOT directly relevant to the objective:

• "Setting up mailer connections" — Keep: onboarding, mailer selection, config forms, connection testing, success/failure. Remove: alerts, reporting, tools, about, logs.
• "First-time user experience" — Keep: onboarding, wizard, first-run, empty states, dashboard (first view), core feature entry. Remove: advanced settings, tools, addons, about.
• "Upsell & monetization audit" — Keep all pages (upsells appear anywhere), but only annotate upsell-related elements.

Show the filtered list to the user in the Step 2 summary before any screenshots begin. Aim for 3-5 screenshots per section — each showing a distinct journey step, not every variation of the same screen.

Step 5b: Collect Plugin Metadata

Gather metadata for each plugin before taking screenshots. This goes into gallery headers and provides context to the ux-reviewer subagent.

For local sites (WP-CLI available):

 plugin list --fields=name,version,author,description,status --format=json --path=""

Extract the target plugin's version, author, and description from the output.

For remote sites (no WP-CLI):

1. Navigate to the Plugins page: agent-browser --session open "/wp-admin/plugins.php"
2. Use snapshot -i to find each target plugin's row
3. Extract version, author, and description from the plugin row text
4. If the Plugins page is inaccessible (permissions), ask the user for plugin versions or note "version unknown"

Store metadata for use in:

• Gallery header (` tag under `: "by Author • vX.X • Description")
• Subagent prompt context (passed to both ux-reviewer and ux-comparator)

Step 6: Handle Interruptions & Blockers

Dismiss these BEFORE taking screenshots:

| Interruption | Solution | |-------------|----------| | Freemius opt-in | Find "Skip" link via snapshot -i, click by [ref=XX] | | Email verification | Click [ref=XX] for "The email is correct" | | Review nag banners | Click dismiss button by [ref=XX] | | Import from other plugin | Click "Skip" or "Got it" by [ref=XX] | | Update notices | Click dismiss by [ref=XX] | | Upgrade/upsell banners | Dismiss or note for annotation |

First-Run Gates

Some plugins gate their entire UI behind a welcome/setup screen that won't dismiss via normal clicks. Try these in order:

1. Direct URL navigation — Skip the gate by navigating to a known admin page: agent-browser --session open "/wp-admin/admin.php?page=-settings"
2. JS dismiss — Use eval to find and click hidden dismiss/skip elements: agent-browser --session eval "document.querySelector('[class*=skip], [class*=dismiss], [class*=close]')?.click()"
3. WP-CLI option bypass — Set the plugin's "setup complete" flag directly: ./wp-cli-local option update _setup_complete 1 (check the plugin's options table for the exact key)
4. Capture as UX observation — If none of the above work, capture the gate screen itself. A first-run screen that blocks access is a legitimate UX finding.

Wizard Progression

Wizards that validate fields before advancing (e.g., requiring SMTP credentials):

1. Fill dummy values — Use plausible-looking test data (e.g., smtp.example.com, port 587, test@example.com). The goal is to reach subsequent screens, not to configure a working connection.
2. WP-CLI option bypass — Set the wizard's step/completion option directly to jump past validation: ./wp-cli-local option update _wizard_step 99
3. Capture the validation state — If the wizard won't advance, capture the error/validation state as a UX observation.

Step 7: Capture Screenshots

Create the screenshots directory:

mkdir -p screenshots/

For each screen/tab, follow shared/common-steps.md → "Screenshot Capture Strategy" — this covers image loading waits and chunked capture for long pages.

Quick summary of the capture flow: 1.

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shub-rajput
• Source: shub-rajput/design-superskills
• License: MIT

Install and usage instructions live in the source repository linked above.