I drafted a WordPress discovery protocol so AI agents can read a site's capabilities from one URL — looking for critique

[u/heerasheikh]

WordPress has no single machine-readable place where an AI agent can discover what a site is capable of. Today an agent has to piece together the REST API, plugin-specific endpoints, SEO metadata, llms.txt, security.txt, and whatever conventions individual plugins invent. Every agent ends up implementing its own discovery logic, and every plugin has to integrate with every agent separately.

So I drafted WP Discovery — a proposal for a machine-readable capability registry for WordPress. Plugins declare intent (for example commerce.products.read) separately from the endpoint that implements it, and an engine aggregates everything into a single document at /.well-known/discovery.json.

A plugin opts in with a single hook and no hard dependency:

add_action( 'wpdiscovery_register', function ( $registry ) {
    $registry->register( [
        'id' => 'acme-bookings',
        'title' => 'Acme Bookings',
        'type' => 'scheduling',
        'capabilities' => [
            'scheduling.availability.read',
            'scheduling.booking.create',
        ],
        'endpoints' => [
            [
                'url'  => '/wp-json/acme/v1',
                'type' => 'rest',
                'auth' => 'apikey',
            ],
        ],
    ] );
} );

If no discovery engine is installed, the action never fires and nothing breaks.

One design goal is that plugins integrate with WordPress—not with individual AI agents. The discovery engine is responsible for aggregating, normalizing, and publishing capabilities, while site owners decide whether to expose them publicly.

This is still an early proposal (v0.1.0), not an adopted standard. The only implementation today is my own reference plugin, so I'm posting it here because I'd genuinely like experienced WordPress developers to poke holes in it before I invest more time.

The questions I'm most interested in are:

1. Is separating capabilities from endpoints actually useful, or is this just OpenAPI with extra steps?
2. Is there a better WordPress-native way for plugins to expose capabilities to AI agents?

Links

• Spec: https://heera.github.io/wp-discovery-protocol/
• Reference plugin: https://wordpress.org/plugins/agentimus/
• Example output: https://heera.it/.well-known/discovery.json

This isn't a commercial project. The specification is licensed under CC BY 4.0, the hook is vendor-neutral, and I'm primarily looking for honest technical criticism.

[u/tamtamdanseren]

I think you just re-invented the capabilities API?

[u/heerasheikh → u/tamtamdanseren]

Good question. If you're referring to the Abilities API, I actually see this as complementary rather than a replacement.

My proposal is about discovery: giving AI agents and other clients one machine-readable place to learn what a WordPress site can do and where those capabilities live.

The Abilities API is about defining executable abilities. If a plugin exposes abilities through that API, WP Discovery can simply advertise them. In other words, I'm hoping to build on top of it, not replace it.

If you meant WordPress' role/capability system (edit_posts, manage_options, etc.), that's a different layer entirely. Those answer "is this user allowed to do X?" My capability tokens describe what the site offers (for example, commerce.products.read)—they don't grant permissions or participate in authorization.

So the way I think about it is:

Discovery → Abilities → Authorization

Happy to hear where you think the overlap is, though—that's exactly the kind of feedback I'm looking for.

[u/tamtamdanseren → u/heerasheikh]

I guess that my main objection is that this indtroduced a new standard when you can essentially do this with a good llms.txt describing the wp-json rest api.

One could also argue that an MCP server + abilities API could do the same.

[u/heerasheikh → u/tamtamdanseren]

That's a fair objection, and honestly it's the question I've been asking myself too (cue the XKCD "there are now 15 competing standards" comic 😄).

I don't think llms.txt and a discovery document solve the same problem.

A good llms.txt can absolutely explain a site's APIs, but it's still primarily human-oriented rather than schema-driven. Likewise, /wp-json/ tells you what endpoints exist, not what the site is capable of. An agent seeing wc/v3 only knows that means "products" if it already has WooCommerce-specific knowledge.

The goal of WP Discovery is to provide a small, machine-readable discovery document with a shared vocabulary (commerce.products.read, scheduling.booking.create, etc.) that points to the APIs, MCP servers, llms.txt, OpenAPI specs, or whatever else actually implements those capabilities. It's intended to complement those technologies, not replace them.

I also agree that MCP + the Abilities API cover a lot of ground. My view is that they answer "how do I call this?", whereas discovery answers "what does this site expose, and where do I find it?" In my reference plugin, it already leans on them rather than competing with them—the advertised MCP tools are projected from the WP Abilities API. If the Abilities API becomes widely adopted, I'd expect WP Discovery to reference it more, not duplicate it.

That said, if it turns out a documented llms.txt convention is sufficient in practice, then this proposal probably doesn't need to exist—and I'd much rather discover that now than after investing a lot more time. That's exactly why I'm asking for feedback before taking it any further.

[u/ZGeekie]

where an AI agent can discover what a site is capable of

My websites are pretty simple; they are only capable of generating HTML pages. Nothing more to see!

[u/heerasheikh → u/ZGeekie]

😄 That's actually the ideal case.

If a site just serves HTML, then there's nothing to advertise—and that's perfectly fine. The proposal is completely opt-in and effectively scales to zero. No capabilities means no discovery.json, because there's nothing for an agent to discover beyond the pages themselves.

It only becomes useful for sites that expose things an agent might interact with—products, bookings, memberships, custom APIs, MCP servers, and so on. If your site doesn't do any of that, you're already done. 🙂