AI Abilities

Overview

Awesome XP exposes 24 abilities through the WordPress Abilities API, surfaced to AI clients by the MCP Adapter’s discover / get-info / execute pattern. The portable operations layer does the real work; each ability is a thin adapter over one operation.

The workflow every agent follows: orient → discover → validate → preview → save draft → publish. Agents never write live artifacts directly.

Naming: awesome/<artifact>-<verb>. Agents scanning a flat discovery list group by name, so the convention does the job a categorised tool list would.

Descriptions are the interface. The descriptions below are the exact text agents see in discovery. Each says what the ability does, when to use it, and what comes before or after.

Capability tiers (custom capabilities mapped to roles, so agent tokens can get author rights and nothing else):

Tier	Covers
read	Guides, discovery, validate, preview, versions, logs
author	Create and update drafts
publish	Publish and roll back versions

Orientation

One ability, and it is the agent’s entry point. Its overview must spell out the lifecycle and the rule to reuse before creating.

Ability	Description (agent-facing)	Inputs → Outputs	Guardrails
awesome/guide-read	Start here. With no topic, returns the Awesome overview, the authoring workflow, and a topic index. With a topic, returns that section of the DSL reference.	topic (optional) → markdown text + related topics	readonly; read tier. Topics stay small: modules and scopes, loops, esc/SQL safety, conditions/modifiers/outputters, pitfalls.

Discovery

Nine readonly abilities that tell the agent what already exists. Quality of everything the agent writes depends on this group.

Ability	Description (agent-facing)	Inputs → Outputs	Guardrails
awesome/app-list	Lists registered apps with name, slug, status, and a one-line purpose. Use before creating an app to check whether one already exists.	optional status filter → app summaries	readonly; read tier
awesome/app-get	Returns an app’s full manifest, including the services, modules, and blocks it uses.	slug, optional version → manifest, current version, drafts	readonly; read tier. Secrets and credentials redacted.
awesome/service-list	Lists available services (core libraries like env, loop, if, mysqli, and custom services), filterable by library. Use to find what exists before writing templates.	optional library, custom_only → service names + summaries	readonly; read tier. Each entry carries agent_allowed from the allowlist.
awesome/service-get	Returns a service’s attributes, return type, and examples.	name → signature, attribute types, return type, examples, agent_allowed	readonly; read tier
awesome/block-list	Lists registered blocks with purpose, fields, and usage count. Check this before creating a block: prefer tokens, then modifiers, then patterns, and create a new block only as a last resort.	optional search text, category → block summaries	readonly; read tier
awesome/block-get	Returns a block’s DGB JSON config and shortcode template.	slug, optional version → config, template, version info, pages using it	readonly; read tier
awesome/token-list	Lists awx design tokens (role tokens by default, grouped by type). Blocks must use these tokens rather than raw values.	optional group, include_primitives (default false) → tokens + purpose	readonly; read tier. No token write ability: tokens come from the moodboard pipeline only.
awesome/dictionary-get	Returns Universal Dictionary parameter names (title, text, items, image, url, etc.) and their meaning by context. Use these names for all block fields.	none → the dictionary	readonly; read tier
awesome/fieldtype-list	Lists DGB field types with their config options. Use when defining block fields.	none → field types, options, examples	readonly; read tier

Verify

Validation is a hard gate: no write succeeds without a validation token that matches the exact code being saved.

Ability	Description (agent-facing)	Inputs → Outputs	Guardrails
awesome/template-validate	Validates shortcode template code for syntax errors and rule violations. Required before any create or update. Returns a validation token on success.	code, context (block / service / app) → valid, errors[] and warnings[] (line, column, rule, fix hint), validation_token (hash of the code, short-lived)	readonly; read tier. Services off the allowlist are errors.
awesome/template-preview	Renders template code with sample data without saving anything. Use after validation to check output.	code, context, sample_attributes → rendered HTML, warnings, any exception	read tier. Database writes run inside a rollback transaction. Curl calls blocked or stubbed. Execution time and output size capped.

Lint rules for template-validate:

• • Unescaped values in SQL (error)

• • Data-returning services without o.set or o.destroy (error)

• • Nested brackets in attributes, or nested curly braces (error)

• • Loop properties accessed without .item (error)

• • Variables in a LIMIT clause (error)

• • Services not on the allowlist (error)

• • Raw colour or spacing values where an awx token exists (warning)

Author (drafts only)

Six abilities that save drafts. Nothing here affects a live artifact, and every call needs a matching validation token.

Ability	Description (agent-facing)	Inputs → Outputs	Guardrails
awesome/block-create	Creates a new block as a draft. Only use after block-list confirms no existing block or variation fits.	DGB config (fields use dictionary names), template, validation_token → slug, version, status: draft	author tier. Rejected without a token matching this exact template. Config validated against the DGB schema. Slug collision is an error, not an overwrite.
awesome/block-update	Saves changes to a block as a new draft version. Does not affect the live version.	slug, config and/or template, validation_token, if_version → new version	author tier; idempotent. Stale if_version fails instead of overwriting.
awesome/service-create	Creates a custom service as a draft.	name, attribute definitions, return type, code, validation_token → name, version	author tier. Stricter allowlist than blocks: no mysqli.multi.cud or transaction writes in v1 unless enabled per site. Namespaced (e.g. custom.*) so it can never shadow a core service.
awesome/service-update	Saves changes to a custom service as a new draft version.	name, changes, validation_token, if_version → new version	Same as service-create; idempotent.
awesome/app-create	Creates an app manifest as a draft. Apps compose existing blocks and services; create those first.	manifest, validation_token → slug, version	author tier. Every referenced block or service must exist (checked on save). Manifests cannot set credentials; humans configure those.
awesome/app-update	Saves changes to an app manifest as a new draft version.	slug, manifest, validation_token, if_version → new version	Same as app-create; idempotent.

Patterns

Patterns get their own Awesome abilities, but are stored as standard WordPress patterns (wp_block posts). WordPress handles storage and revisions; the abilities add the Awesome-specific validation that generic pattern or post abilities cannot. A pattern is block markup, not shortcode code, so it is validated inside create and update rather than through a validation token.

Ability	Description (agent-facing)	Inputs → Outputs	Guardrails
awesome/pattern-list	Lists block patterns built from Awesome blocks, with title, category, and whether each is synced. Check this before composing a new layout.	optional search, category → pattern summaries	readonly; read tier
awesome/pattern-get	Returns a pattern’s block markup and the blocks it uses.	id → markup, blocks used, synced flag, revision	readonly; read tier
awesome/pattern-create	Creates a pattern as a draft by composing existing blocks. Use when a layout can be built from registered blocks; create a new block only if no combination works.	title, category, block markup, synced (default false) → id, status: draft	author tier. Every block must be registered or on the core-block allowlist. Attributes must match each block’s DGB schema. Token classes must exist.
awesome/pattern-update	Saves changes to a pattern as a new draft.	id, markup, if_version → new version	author tier; idempotent. A synced pattern goes live only through version-publish, because the change reaches every page using it.

Lifecycle

Three abilities that move versions between draft and live. Publish and rollback are the only destructive abilities in v1.

Ability	Description (agent-facing)	Inputs → Outputs	Guardrails
awesome/version-list	Lists versions of a block, service, app, or pattern with status, author, and date. Use to find a draft to publish or a version to roll back to.	artifact_type, slug → versions + diff summary against live	readonly; read tier
awesome/version-publish	Makes a draft version live. Affects every page using this artifact.	artifact_type, slug, version → live version, affected page count	destructive; publish tier. Re-validates on publish. Disabled on production unless a site flag allows it. Consider human confirmation outside the agent in v1.
awesome/version-rollback	Restores a previous version as live.	artifact_type, slug, version → live version	destructive; publish tier. Same environment rule as publish.

Debug

One ability that lets the agent diagnose its own failures after preview or publish.

Ability	Description (agent-facing)	Inputs → Outputs	Guardrails
awesome/log-list	Returns recent exceptions from the Awesome error log, filterable by artifact. Use after preview or publish to diagnose failures.	optional artifact, time window, limit → entries (message, location, count, last seen)	readonly; read tier. Request data and PII in log payloads redacted. Hard limit on result size.

Cross-cutting guardrails

These apply to every ability, and they are enforced server-side rather than left to the agent’s good behaviour.

• • Validation gate: writes require a validation token matching the submitted code, so skipping validate is impossible, not just discouraged.

• • Drafts only for agents: nothing an agent writes goes live directly; promotion sits in a separate capability tier.

• • No delete abilities in v1: archiving is a human action.

• • Audit log: each call records the client or token, ability, artifact, version, and outcome.

• • Errors name the next step: for example “Call awesome/template-validate first” or “Slug exists; use awesome/block-update”.

• • One allowlist: a single config applied to blocks, services, and apps with different strictness, and surfaced through service-list.

• • Limits: rate limits plus size caps on code, output, and preview time.

Serving the skills through MCP

The awesome-enterprise-shortcodes and awesome-css-design-system skills move into the Awesome XP plugin and are served by awesome/guide-read. Every agent connecting to a site gets them without anyone sharing files, and the content matches the framework version installed on that site.

Tools, not resources. The MCP Adapter can expose an ability as a tool, a resource or a prompt. Resources look like the natural fit for documentation, but many clients only show them when a user attaches them by hand. Tools are the one primitive every agent can call by itself, and the only type reached through discover/execute. The same content can optionally also be registered as resources for clients that handle them well.

Split each skill. Stable conventions become guide topics. Live reference data comes from discovery abilities generated from the site itself, so it never drifts from the code.

Skill	Stable conventions → guide topics	Live reference → discovery abilities
awesome-enterprise-shortcodes	Execution lifecycle, syntax and typecasting, scopes, esc/SQL safety, pitfalls	Services, libraries and attributes → service-list / service-get, from the runtime registry
awesome-css-design-system	Two-layer token model, naming rules, tokens → modifiers → patterns → blocks, writing block CSS	Token values → token-list, from the site’s tokens.css / theme.json

How it fits together:

1. 1. Single source. Conventions live as markdown files in the plugin repo, one file per topic, versioned with the framework.

1. 1. Progressive loading. awesome/guide-read with no topic returns the overview, workflow and a topic index covering both skills. With a topic, it returns that file.

1. 1. Entry point. The adapter’s server guide tells agents in one line to call awesome/guide-read before any Awesome work. This line replaces “install the skill”.

1. 1. Pointers in descriptions. For example, block-create’s description says “read guide topic css-tokens first”.

Trade-off. Native skills load automatically when a task matches. Over MCP the agent must choose to call the guide, so the entry-point line and description pointers carry real weight. The validation gate is the backstop: an agent that skips the guide still cannot save code that breaks the conventions.

Optional: an awesome/skill-export ability returns assembled SKILL.md files from the same source, for installing the skills in Claude Code or the Claude apps.

Decisions and open questions

All four original assumptions are settled.

• • Shared parser (confirmed): services and app manifests use the same shortcode DSL and parser as block templates, so template-validate and its lint rules cover all three.

• • Modules and templates (settled): templates live inside modules, and modules are written only as part of a service or app. No separate abilities are needed.

• • Patterns (settled): own abilities over WordPress pattern storage; see Patterns.

• • Versioning (settled): copy, then merge on publish. Block definitions are aw_gb_blocks posts, and modules already use revisions, so every artifact is a post with revision history.
    1. 1. Editing an existing artifact creates a linked copy (forked_from: <slug>), hidden from the inserter. The copy is the draft.
    1. 1. The agent validates and previews the copy; the live artifact is never touched.
    1. 1. version-publish writes the copy’s content into the original post under the same slug, then removes the copy. The previous content becomes a WordPress revision.
    1. 1. version-rollback restores a revision; version-list reads revisions plus any open copy.
    1. 1. Pages keep pointing at the original slug, so nothing needs migrating.

To check: aw_gb_blocks has revisions support enabled. The DGB config is stored in post content, so revisions capture it fully.

`