A comprehensive WordPress diagnostics and site builder plugin. Connects via SSH, local directory, Docker container, or git repository to run structured investigations with 21 diagnostic skills. Builds complete WordPress sites from natural language, visual designs, or URLs with 9 build skills — packaged as Local WP importable zips with MCP adapter pre-installed.
Works as a Claude CoWork plugin (Claude Desktop) or a Claude Code CLI addon. Nothing is installed on the WordPress site.
- Claude Desktop with CoWork support or Claude Code CLI
- Docker Desktop (required for
/buildand/modifycommands) - Access to the target WordPress site (SSH, local path, Docker, or git) for diagnostics
jqinstalled locallyrsyncinstalled locally (for SSH connections)- Optional: Local WP for importing built sites (output zips are Local WP importable)
- Optional: WP-CLI on the remote server (enables core integrity checks, user audits, cron analysis, and profiling)
- Optional: Playwright (
npx playwright install chromium) for URL clone mode
- Download or clone this repository
- Zip the folder:
zip -r wordpress-expert.zip wordpress-expert/ -x "*.git*" "*.planning*" ".sites/*" "memory/*" "sites.json"
- Open Claude Desktop
- Go to the CoWork tab in the sidebar
- Click Add Plugin (or the + button)
- Select Upload Plugin and choose the
wordpress-expert.zipfile - The plugin will appear in your CoWork tab ready to use
npx wpxpertThis installs commands and skills to ~/.claude/ so they're available in all Claude Code sessions. Commands are namespaced as /wpxpert:connect, /wpxpert:diagnose, /wpxpert:investigate, /wpxpert:batch, /wpxpert:status, /wpxpert:build, /wpxpert:modify.
To uninstall:
npx wpxpert --uninstallBuild a WordPress site from scratch — four creation modes:
/build --blank # Blank WordPress install
/build "a portfolio for a photographer" # Natural language site creation
/build --visual ./figma-export/ # Custom FSE theme from design exports
/build --from-url https://example.com # Visual reproduction from URL
Blank mode generates a WordPress installation with Docker MySQL, WP-CLI, MCP adapter pre-installed, and git versioning — packaged as a Local WP importable zip.
Natural language mode selects a matching WP.org theme, installs relevant free plugins, generates AI placeholder content (pages, posts, menus, images), and produces a SETUP.md checklist.
Visual mode creates a custom FSE block theme from structured HTML/CSS exports (Figma, Canva, Adobe XD, Sketch, Framer, Miro, InDesign, Illustrator, Photoshop) with design token extraction and Google Fonts bundling.
URL mode scrapes a URL with Playwright, checks robots.txt, replaces all content with AI-generated placeholders, detects dynamic features, and generates an FSE theme through the same visual pipeline.
Start an interactive modification session for any WordPress directory:
/modify ./my-wp-site # Start session, prompt for first change
/modify ./my-wp-site "change the primary color to green" # Execute first step, then continue
/modify ./my-wp-site --visual ./updated-export/ # Visual re-export as first step
Each modification is git-committed immediately for rollback granularity. Say "done" when finished to produce a versioned output folder and zip. Works on any WordPress directory — /build output, Local WP sites, or manual installs. Docker is started lazily only when content or plugin changes are needed.
Connect to a WordPress site via SSH, local directory, Docker container, or git repository. Detects WordPress installation, discovers WP-CLI, syncs files locally, and saves the connection profile.
/connect
/connect mysite.com
/connect /var/www/wordpress
/connect docker:my-wp-container
Run a thorough diagnostic investigation with structured workflow:
- Intake -- gathers context about your concern
- Scout -- SSH reconnaissance for environment clues
- Plan -- chooses which skills to run based on concern + scout data
- Execute -- runs skills in parallel waves
- Review -- verifies findings address your concern
- Report -- generates report with confidence rating
/investigate
/investigate my site got hacked
/investigate security on mysite
/investigate slow performance on production
Each step is configurable via config.json. Use /investigate for thorough analysis and /diagnose for quick scans.
Run diagnostic scans across all skills. Supports four modes:
- full (default) -- all diagnostic skills
- security-only -- core integrity, config security, user audit
- code-only -- code quality, malware scan
- performance -- N+1 queries, cron analysis, WP-CLI profiling, autoload bloat
/diagnose
/diagnose security only
/diagnose code only on mysite
/diagnose performance
Features inline progress feedback, skip-and-continue error recovery, A-F health grading, trend badges, and suggested next actions.
Run diagnostics across multiple saved site profiles with a comparison matrix.
/batch
/batch security only
Runs each site sequentially with per-site status lines, then produces a side-by-side comparison matrix of findings across all sites.
View connected sites, health summaries, and suggested next actions.
/status
/status remove mysite
/status default mysite
/status rename oldname newname
| Skill | What it does |
|---|---|
| Build Scaffold | Docker MySQL, WP-CLI pipeline, SQL export, Local WP zip packaging, build.json manifest |
| Build MCP | MCP adapter pre-installation and activation with STDIO transport config |
| Build Theme | WP.org FSE theme selection and installation from NL description |
| Build Content | WP.org plugin installation, AI placeholder content (pages/posts/menus/images), DB re-export |
| Build Setup | SETUP.md generation with priority-ordered plugin configuration guidance |
| Build Visual | Custom FSE block theme from HTML/CSS with design token extraction and Google Fonts |
| Build Scrape | Playwright URL scraping with robots.txt, content sanitisation, dynamic feature detection |
| Build Git | wp-content git init, smart .gitignore, conventional commits per build stage |
| Build Modify | Session-aware per-step execution — surgical NL/visual modifications, lazy Docker, per-step git commits, deferred versioned zip on completion |
| Skill | What it checks | Requires WP-CLI |
|---|---|---|
| Core Integrity | WordPress core file checksums against known-good values | Yes |
| Config Security | wp-config.php for debug mode, salts, file editing, DB prefix | No |
| User Audit | Admin usernames, role distribution, inactive accounts | Yes |
| Version Audit | WordPress, plugin, and theme update status | Yes |
| Malware Scan | Pattern-based detection of backdoors, obfuscation, shells | No |
| HTTPS Audit | SSL configuration, FORCE_SSL_ADMIN, mixed content indicators | No |
| File Permissions | File and directory permissions against WP security recommendations | No |
| Skill | What it checks | Requires WP-CLI |
|---|---|---|
| Code Quality | AI-powered analysis of active theme and custom plugins | No |
| Skill | What it checks | Requires WP-CLI |
|---|---|---|
| Autoload Analysis | Autoloaded option bloat detection and plugin attribution | Yes |
| Transient Health | Expired transient buildup and cleanup recommendations | Yes |
| Revision Analysis | Post revision volume by type with storage impact estimates | Yes |
| Skill | What it checks | Requires WP-CLI |
|---|---|---|
| N+1 Query Detection | N+1 query patterns in theme and plugin code with confidence ratings | No |
| Cron Analysis | Overdue, duplicate, and excessively-frequent scheduled jobs | Yes |
| WP-CLI Profile | Stage and hook timing analysis for performance bottlenecks | Yes |
| Skill | What it checks | Requires WP-CLI |
|---|---|---|
| Architecture Review | CPT misuse, hook abuse patterns, caching anti-patterns | No |
| Architectural Narrative | AI-synthesized health narrative across all diagnostic domains | No |
| Skill | What it does |
|---|---|
| Intake | Gathers context from the user -- symptoms, timeline, environment, scope, urgency |
| Site Scout | SSH reconnaissance -- error logs, recent file changes, PHP environment, disk usage |
| Scan Reviewer | Verifies findings address the original concern, checks for contradictions |
| Skill | What it does |
|---|---|
| Report Generator | Compiles findings into structured markdown reports with A-F health grades |
| Trend Tracker | Cross-scan NEW/RESOLVED/RECURRING classification with inline report badges |
All findings use three severity levels: Critical, Warning, and Info.
Reports are saved to memory/{site-name}/latest.md with A-F health grades and trend badges.
WordPress Expert can connect to sites through multiple source types:
| Source | Command | Use case |
|---|---|---|
| SSH | /connect user@host.com |
Production/staging servers |
| Local | /connect /var/www/wordpress |
Local development environments |
| Docker | /connect docker:container-name |
Docker-based development |
| Git | /connect git:repo-url |
Code-only analysis from repositories |
All sources sync to a local .sites/ directory for analysis. SSH connections use rsync with dry-run-first safety. Local and Docker connections use direct file copy.
.claude-plugin/
plugin.json # Plugin manifest (skills + commands registry)
commands/
batch/COMMAND.md # /batch workflow
build/COMMAND.md # /build workflow (blank, NL, visual, URL modes)
connect/COMMAND.md # /connect workflow
diagnose/COMMAND.md # /diagnose workflow (quick scan)
investigate/COMMAND.md # /investigate workflow (full investigation)
modify/COMMAND.md # /modify workflow (post-creation modifications)
status/COMMAND.md # /status workflow
skills/
build-*/ # 9 build skill specifications
diagnostic-*/ # 15 diagnostic skill specifications
intake/ # Context gathering before diagnostics
site-scout/ # SSH reconnaissance
scan-reviewer/ # Post-scan findings verification
report-generator/ # Report compilation and health grading
trend-tracker/ # Cross-scan trend analysis
vendor/
mcp-adapter/ # Pre-compiled WordPress MCP adapter
references/ # wordpress-agent-skills patterns (16 SKILL.md files)
config.json # Workflow toggles
sites.json # Connection profiles (gitignored)
.sites/ # Synced site files (gitignored)
memory/ # Diagnostic reports, case logs, and history (gitignored)
bin/
install.js # Claude Code CLI installer
tests/
validate-plugin.sh # Plugin structure validation
- SSH credentials are never stored in version-controlled files or logged to output
rsync --deleteis never used (no risk of deleting remote files)- All rsync operations run
--dry-runfirst - Files are pulled read-only; the plugin never pushes changes to the remote site
sites.jsonand.sites/are gitignored by default- No
.envfiles are committed - Build admin passwords are displayed in terminal only — never stored in files
- Docker containers are cleaned up via EXIT traps even on build failure
- URL clone mode checks robots.txt and displays copyright disclaimers before scraping
See CONTRIBUTING.md for how to add new skills, commands, and improvements.