Working with AI – WordPress Plugin Boilerplate
This plugin setup is optimized for AI-assisted development. It provides one unified wp-plugin-bp skill plus focused WordPress skills that guide AI agents to work effectively with your plugin.
Agent skills can be refreshed from upstream project conventions.
How It Works
Section titled “How It Works”The AI integration consists of two layers that work together:
1. AGENTS.md — The Rulebook
Section titled “1. AGENTS.md — The Rulebook”The AGENTS.md file in the root directory is the primary instruction set for AI agents. It contains:
- High-level architecture guidance
- Coding standards and conventions
- Quick reference for key primitives
- Pointers to detailed documentation
This file is your single source of truth for how AI agents should interact with your codebase.
2. wp-plugin-bp Skill And WordPress Skills
Section titled “2. wp-plugin-bp Skill And WordPress Skills”The wp-plugin-bp skill lives in .agents/skills/wp-plugin-bp/ and handles:
- Multi-file operations
- Decision trees and conditional logic
- Integration with external tools
- Automatic task routing for natural-language requests
Official WordPress skills live in .agents/skills/wp-*/ and provide focused guidance for blocks, Interactivity API, PHPStan, project triage, and REST API work.
Agents should infer the right task from natural language. For example, “sync this plugin with upstream project conventions” routes to upgrade.
Available Tasks
Section titled “Available Tasks”| Task | Description |
|---|---|
upgrade [scope] | Sync with the latest upstream project conventions. Natural prompts like “update plugin conventions” route here. |
translation [lang1 lang2...] | Update or create translations. Without arguments: updates existing .po files. With arguments: creates or updates specific languages. |
testing [target] | Write or debug PHPUnit application tests using wp-env conventions. |
action-scheduler [target] | Add or test Action Scheduler integration. |
qa [scope] | Run configured quality checks and fix errors. |
readme [target] | Update README.md with current plugin information. |
wp-skills [skillnames] | Download and install official WordPress agent skills. |
blocks [target] | Scaffold or maintain Gutenberg blocks. |
abilities [target] | Implement or update Abilities API code. |
bundling [target] | Work on wp-scripts entry points, assets, or enqueueing. |
acf [target] | Add or maintain ACF integration patterns. |
sentry [target] | Add or maintain Sentry integration patterns. |
Built-in Skills
Section titled “Built-in Skills”wp-plugin-bp
Section titled “wp-plugin-bp”The wp-plugin-bp skill is the unified router for plugin workflows. Its SKILL.md stays small, command-specific files live in .agents/skills/wp-plugin-bp/references/, and detailed docs are linked as doc-*.mdx references.
The initial Composer package includes .agents/ so setup can run wp-plugin-bp/scripts/plugin-replace.php for identity replacement. Setup removes .agents/ after replacement, adds .agents/ to the initialized plugin’s .gitignore, then asks whether to install agent skills for ongoing AI-assisted work.
Installed skills are intentionally untracked in initialized plugins. Use npx skills update -p to refresh project skills from their upstream source.
Skills are not available?
Section titled “Skills are not available?”Install the skills from the upstream repository:
npx skills add https://github.com/JUVOJustin/wordpress-plugin-boilerplate --skill=*WordPress Agent Skills
Section titled “WordPress Agent Skills”The WordPress project provides official skills for WordPress development. This project includes the default set installed from https://github.com/WordPress/agent-skills:
| Skill | Purpose |
|---|---|
wp-block-development | Create, modify, and debug Gutenberg blocks |
wp-interactivity-api | Work with the Interactivity API for dynamic blocks |
wp-phpstan | PHPStan analysis with WordPress-specific rules |
wp-project-triage | Project analysis and task management |
wp-rest-api | REST API routes, auth, and schema guidance |
Ask the wp-plugin-bp skill to run the wp-skills workflow to refresh these skills or install another official WordPress skill.
Tips for Effective AI Collaboration
Section titled “Tips for Effective AI Collaboration”- Be specific: Instead of “fix the bug”, say “fix the PHP notice in src/Admin/Settings.php line 42”
- Reference conventions: Mention “follow the Loader pattern” or “use the enqueue_entrypoint method”
- Use the
wp-plugin-bpskill: It is faster and more consistent than describing the same task repeatedly - Update docs: When you add new patterns, update
AGENTS.mdso future AI interactions benefit