Perxel Blocks

A Claude Code plugin for scaffolding, auditing, and managing custom **ACF Gutenberg blocks ** for WordPress — with Tailwind CSS integration and a structured, production-ready workflow. Tested with NectarBlocks.

Example use cases

Example 1: Starting a new WordPress project

Run /perxel-blocks:init my-client-site — the plugin asks for project name, theme slug, author, and which optional features (Tailwind, TypeScript) to include, then scaffolds the full theme structure.

Example 2: Adding a new block

Run /perxel-blocks:create-block hero-banner — generates block.json, render.php, fields.json, and registers the block in blocks.json automatically.

Example 3: Auditing before a handoff

Run /perxel-blocks:audit-blocks — instantly checks all blocks for missing files, invalid timestamps, unregistered folders, and render issues. No AI, runs in seconds.

<img width="1173" height="340" alt="audit-blocks" src="https://github.com/user-attachments/assets/1802a04f-293b-4720-892c-6f3d55c0791a" />

Example 4: Deep content review

Run /perxel-blocks:audit-blocks-deep — AI reviews block labels, field quality, admin render justification, and content consistency across the project.

<img width="1309" height="882" alt="audit-blocks-deep" src="https://github.com/user-attachments/assets/18ed1a36-f88b-4c93-a120-6fb80467e68e" />

Example 5: Asking the agent

Talk to the perxel-blocks-dev agent when you're unsure about block structure, ACF field setup, PHP patterns, or Tailwind config — no need to provide context, it knows the workflow.

Install

From GitHub (recommended):

1. Add the marketplace once

claude plugin marketplace add perxel/perxel-blocks

2. Install the plugin

claude plugin install perxel-blocks@perxel --scope project

From official Claude marketplace (if listed):

claude plugin install perxel-blocks@claude-plugins-official --scope project

Local install (for testing or offline use):

1. Clone the repo

git clone https://github.com/perxel/perxel-blocks.git

2. Register the local folder as a marketplace (run once)

claude plugin marketplace add /your/path/to/perxel-blocks

3. Install from it

claude plugin install perxel-blocks@perxel --scope project

Update

claude plugin update perxel-blocks@perxel

Local install — pull the latest and reinstall:

cd /your/path/to/perxel-blocks && git pull
claude plugin install /your/path/to/perxel-blocks --scope project

Plugin updates are not automatic. Always bump the version in .claude-plugin/plugin.json when publishing changes — Claude Code uses the version number to detect updates.

Commands

Command	What it does
/perxel-blocks:init <project-name>	Scaffold a new WordPress theme with full perxel-blocks setup
/perxel-blocks:create-block <name>	Create a new ACF block with all required files
/perxel-blocks:audit-blocks	Audit all blocks against conventions
/perxel-blocks:audit-blocks-deep	Deep AI audit — content quality, labels, admin render justification

Agent

The perxel-blocks-dev agent has full knowledge of the workflow built in. Ask it anything about block structure, PHP patterns, ACF fields, asset loading, or Tailwind setup — no context needed.

Optional features

The core workflow is PHP-first. The following are opt-in during /perxel-blocks:init:

• Tailwind v4 — CSS build pipeline with per-developer CSS support
• TypeScript + tsup — JS bundler for npm packages and block scripts
• Per-developer CSS — each developer builds their own Tailwind output independently

Documentation

• Introduction — what perxel-blocks is and who it is for
• Workflow — step-by-step development guide
• Conventions — block structure rules and patterns

Requirements

• WordPress 6.0+
• ACF Pro
• PHP 8.0+
• Node.js + pnpm (if using Tailwind or TypeScript)

License

MIT — perxel