A Self-documenting System

WPX is a theme that explains itself.

I’ve found agents work best when they receive proper guidance before they touch code. Each registered skill opens with front matter that explains what it covers:

---
name: cta-component
description: CTA native Gutenberg block contract.
---Code language: YAML (yaml)

During development, a Vite watcher gathers that front matter into a single index with one line per skill. An agent searches the index by path instead of reading it:

$ rg -n -F "presentation/components/blocks/cta/" .agents/skills/skill-router/references/skill-index.md
66:- `cta-component` | `presentation/components/blocks/cta/.agents/skills/cta-component/SKILL.md` | CTA native Gutenberg block contract.Code language: Bash (bash)

The match names the owner and its skill. The agent reads that skill and the component’s contract, edits the files they describe, and updates the guidance when the behavior changes. A change to the CTA block reads about 51 KB this way, less than 1 percent of the theme’s 6.2 MB of source.

The Back end

Components that render themselves.

On the PHP side, namespaces mirror folders. One autoloader in functions.php resolves any WPX class from its path, so subsystems boot themselves and components load only when a page uses them:

spl_autoload_register(function ($class) {

    $prefix = 'WPX\\';

    if (strpos($class, $prefix) !== 0) {
        return;
    }

    $relative = substr($class, strlen($prefix));

    $normalized = str_replace('\\', '/', $relative);

    $path = get_template_directory() . '/' .
        strtolower($normalized) . '.php';

    if (file_exists($path)) {
        require_once $path;
        return;
    }

    // Falls back to kebab-case filenames for multi-word class names.
});Code language: PHP (php)

Templates and blocks render components by slug. The renderer turns the slug into a class, asks it for data, and returns its markup unchanged:

// single-wpx-portfolio.php
echo wpx_component( 'interfaces/hero', [ 'post_id' => get_the_ID(), 'post_type' => 'wpx-portfolio' ] );Code language: PHP (php)

Each component keeps its code, its editor script, and its documentation in one folder:

presentation/components/blocks/cta/
├── block.json
├── colors.js
├── component.php
├── editor.js
├── motif.php
├── networks.json
├── readme.txt
├── schema.php
└── .agents/skills/cta-component/
    ├── SKILL.md
    └── references/contract.md

The Abilities Framework

An interface for other agents.

WPX also describes itself to agents outside the repository. Thirteen adapters register with the WordPress Abilities API and mark themselves public for MCP clients. Most are read-only views of site content, such as the portfolio, a project's context (or in the case of this site, the City leaderboard), and one composes portfolio markup for review without saving it:

// abilities/abilities.php
wp_register_ability( 'wpx/' . $definition['name'], [
    'label' => $definition['label'],
    'description' => $definition['description'],
    'category' => 'wpx',
    'input_schema' => $definition['input'],
    'output_schema' => $definition['output'],
    'permission_callback' => static fn( $input ) => $permission( Support::input( $input ) ),
    'execute_callback' => static fn( $input ) => $adapter::execute( Support::input( $input ) ),
    'meta' => [
        'public' => true,
        'show_in_rest' => true,
        'mcp' => [ 'public' => true ],
    ],
] );Code language: PHP (php)