Skip to content

Abilities: Add the core/templates-query ability - #1309

Draft
yaman-694 wants to merge 2 commits into
WordPress:developfrom
yaman-694:add/templates-query-ability
Draft

yaman-694 wants to merge 2 commits into
WordPress:developfrom
yaman-694:add/templates-query-ability

Conversation

@yaman-694

@yaman-694 yaman-694 commented Nov 6, 2026 •

Copy link
Copy Markdown

What?

Closes #1303

Adds core/templates-query, a read-only ability that reports whether the active theme is a block theme, its name, and the block templates the site has for it.

Why?

An agent that wants to change how a page looks needs to know first whether the theme supports block templates, which templates exist, and which ones a user has already edited.
Today the only way to find out is to try, as the AI Workspace's template proposals (#1298) do with their own wp_is_block_theme() and get_block_template() checks.
This ability lets any consumer (the workspace, MCP clients, other plugins) ask first.

How?

The ability follows how the plugin registers core/content-query and core/settings-get:

  • includes/Abilities/Templates/Templates.php registers the ability on wp_abilities_api_init at priority 11, and stands down when an ability with the same name is already registered.
  • includes/Abilities/Gated/Templates_Query.php gates it behind the Custom Abilities experiment, and it is added to Gated_Abilities.
  • It takes no input. An empty object is accepted, because clients such as the Abilities Explorer and MCP clients always send one.
  • It returns:
    {
      "block_theme": true,
      "theme": "Twenty Twenty-Five",
      "templates": [
        { "slug": "404", "title": "Page: 404", "source": "theme", "has_theme_file": true },
        { "slug": "single", "title": "Single Posts", "source": "custom", "has_theme_file": true }
      ]
    }
  • The templates come from core's get_block_templates(), so they match what the Site Editor shows: theme files (theme), templates a user created or edited (custom), and templates a plugin registered (plugin).
    has_theme_file tells an edited theme template (which Reset can bring back) from one a user created.
  • Templates are sorted by slug, because get_block_templates() lists edited templates before theme files.
  • It requires edit_theme_options, the capability the Site Editor needs, and is annotated read-only, non-destructive and idempotent.
    It is marked public and show_in_rest, so it is available over REST and, through the MCP Adapter, over MCP.
  • source is a string, not an enum: it comes from core and from filters, and an unexpected value should not fail the whole response.
  • The input schema has no empty properties key: PHP encodes an empty array as the JSON array [], which the JSON Schema validator in @wordpress/abilities rejects before the ability runs.
    A test pins this.

Decisions to confirm

These follow the questions on #1303; happy to change any of them:

  1. Only wp_template is listed, not template parts (wp_template_part).
  2. The ability is gated behind Custom Abilities and marked public, like the other core/* abilities.
  3. The name is core/templates-query, as proposed in the issue.

Use of AI Tools

Testing Instructions

  1. Enable the Custom Abilities experiment in Settings > AI.
  2. Open Tools > Abilities Explorer and run core/templates-query with {}.
  3. With a block theme such as Twenty Twenty-Five, the result has block_theme: true and the theme's templates with source: "theme".
  4. Edit a template in the Site Editor (for example Single Posts) and run it again: that template now has source: "custom" and has_theme_file: true.
  5. Create a new template for one page and run it again: it has source: "custom" and has_theme_file: false.
  6. Switch to a classic theme and run it again: block_theme is false and templates is empty.
  7. As an editor, the ability is refused.

Automated tests:

  • npm run test:php -- --filter 'TemplatesTest|Gated_AbilitiesTest' (13 new tests, using a block and a classic fixture theme in tests/data/themes).
  • npm run test:e2e -- tests/e2e/specs/abilities/core-templates-query.spec.js, which runs the ability through the client-side Abilities API.
  • The full PHP suite (2,878 tests), PHPStan and PHPCS pass locally.

The ability was also run end to end over MCP through the MCP Adapter's default server, where it is listed by mcp-adapter-discover-abilities and returns the site's templates through mcp-adapter-execute-ability.

Changelog Entry

Added - New core/templates-query ability that reports whether the active theme is a block theme and lists its block templates, with where each one comes from and whether the theme ships it as a file.

Open WordPress Playground Preview

Adds a read-only ability that reports whether the active theme is a block
theme, its name, and the block templates the site has for it. Each template
has its slug, title, source (theme, custom or plugin) and whether the theme
ships it as a file, so an agent can check what it may change before it
proposes a template.

The ability is gated behind the Custom Abilities experiment, requires
`edit_theme_options`, is public, and stands down when the ability is already
registered. Templates are sorted by slug. Template parts are not included.

Fixes WordPress#1303.
@codecov

codecov Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.11%. Comparing base (4aea8f6) to head (c72728f).

Additional details and impacted files
@@              Coverage Diff              @@
##             develop    #1309      +/-   ##
=============================================
+ Coverage      85.03%   85.11%   +0.08%     
- Complexity      4832     4843      +11     
=============================================
  Files            190      192       +2     
  Lines          17950    18051     +101     
=============================================
+ Hits           15263    15364     +101     
  Misses          2687     2687              
Flag Coverage Δ
unit 85.11% <100.00%> (+0.08%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@jeffpaul

Copy link
Copy Markdown
Member

@yaman-694 would you mind porting this over to https://github.com/WordPress/abilities?

@jeffpaul jeffpaul modified the milestones: 1.6.0, 1.7.0 Nov 18, 2026
@yaman-694

Copy link
Copy Markdown
Author

Sure @jeffpaul I will work on that.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a read ability for block templates and whether the active theme supports them

2 participants