ship-wp-ability skill: prefer shared categories and require mcp tool meta (#48838)

Author: enejb

.agents/skills/ship-wp-ability.md

@@ -83,8 +83,12 @@ Do NOT consolidate across these hard boundaries:
 
 Then the rest of the naming:
 
-- **Category slug:** kebab-case, plugin-scoped. Good: `jetpack-monitor`, `jetpack-forms`, `jetpack-modules`. Bad: `monitor`, `forms`.
-- **Ability slugs:** `<category>/<verb>-<object>`, e.g. `jetpack-monitor/get-monitor-status`.
+- **Category slug — prefer a core / shared category over a plugin-scoped one when the abilities are general site management.** Think of categories as broad surface labels for the agent, not as plugin namespaces. If the abilities act on the *site* (backup/restore, modules, connection state, content), use the upstream-registered `site` category. Reach for a plugin-scoped slug only when the abilities are genuinely product-specific and don't fit any shared bucket.
+  - **Use a shared/core category** (`site`, etc.) for: backup/restore, module toggles, connection-state readers, content-management actions, anything an agent would discover under "manage this site".
+  - **Use a plugin-scoped slug** (`jetpack-forms`, `jetpack-boost`) when the abilities cover a product-specific surface that wouldn't sit naturally next to another plugin's tools.
+  - Bad either way: bare single words you invent (`monitor`, `cache`) — pick a real shared category or namespace it.
+  - **If the category you pick is registered upstream**, override `register_category()` to a no-op and skip `wp_register_ability_category()`. The base `Registrar` still hooks the categories-init callback; making it a no-op avoids "already registered" notices. `get_category_definition()` stays on the class to satisfy the abstract contract but isn't called.
+- **Ability slugs:** `<product-or-feature>/<verb>-<object>`, e.g. `jetpack-monitor/get-monitor-status`, `jetpack-backup/get-backup-overview`. The slug prefix is a product/feature namespace and is independent of the category — abilities under the shared `site` category still use `jetpack-<feature>/...` slugs.
 - **Class name:** `<Name>_Abilities` (e.g. `Monitor_Abilities`, `Forms_Abilities`, `Modules_Abilities`).
 - **Namespace:** plugin context (Case A, Case C) → `Automattic\Jetpack\Plugin\Abilities`. Package context (Case B) → `Automattic\Jetpack\<Pkg>\Abilities`.
 
@@ -115,6 +119,7 @@ For every entry in `get_abilities()`:
 - `execute_callback` — `[ __CLASS__, 'method_name' ]`. Method signature is `( $input = null )`. Return value is a plain array (or `WP_Error`). Keep the shape **high-signal** — don't return raw `$mod` / `WP_Post` / option dumps; summarize. See the anti-patterns section of `references/agent-ergonomics.md`.
 - `permission_callback` — `[ __CLASS__, 'can_method' ]`. See the permissions table below.
 - `meta.annotations` — `readonly`, `destructive`, `idempotent` booleans. These must match execute behavior; `wp-abilities-verify` will flag mismatches.
+- `meta.mcp` — every ability gets `'mcp' => array( 'public' => true, 'type' => 'tool' )`. This is what surfaces the ability to MCP-bridged AI agents as a tool. Matches the convention used by Stats / Boost / Modules abilities; leaving it off makes the ability invisible to MCP consumers even though it shows up in `/wp-abilities/v1/abilities/`. Flip `public => false` only when the ability is for internal callers and explicitly shouldn't be agent-discoverable.
 - `meta.show_in_rest` — `true` when the ability should be callable via REST.
 - **Do NOT set `category`** in the spec. `Registrar` auto-injects it. Setting it duplicates info that drifts.
 - `WP_Error` codes — use the shared vocabulary in `wp-abilities-api/references/error-code-vocabulary.md` (`<plugin>_not_initialized`, `<plugin>_missing_<field>`, `<plugin>_invalid_<field>`, `<plugin>_<resource>_data_unavailable`). The **message** should tell the agent *what to do next* — e.g. "Unknown module slug. Call jetpack-modules/get-modules to enumerate." — not just restate the error condition.

.agents/skills/ship-wp-ability/references/class-skeleton.md

@@ -16,6 +16,33 @@ Do not re-implement any of this in the subclass:
 - **WP < 6.9 compatibility** — guards every call to `wp_register_ability_category()` and `wp_register_ability()` with `function_exists()`.
 - **Category auto-injection** — if a spec in `get_abilities()` omits the `category` key, the base class injects `get_category_slug()`. Don't set `category` manually.
 
+### When the category is registered upstream (preferred for site-wide abilities)
+
+The skill steers you toward shared/core categories (e.g. `site`) when the abilities are general site management. In that case **you don't register the category** — WordPress core / wpcom already did. Override `register_category()` to a no-op:
+
+```php
+public static function get_category_slug(): string {
+    return 'site';
+}
+
+// Required by the abstract parent but unused — the `site` category is
+// already registered upstream so we don't re-declare it.
+public static function get_category_definition(): array {
+    return array(
+        'label'       => __( 'Site', 'jetpack-<pkg>' ),
+        'description' => __( 'Site-wide management abilities (registered upstream).', 'jetpack-<pkg>' ),
+    );
+}
+
+// `Registrar::init()` still hooks this onto `wp_abilities_api_categories_init`;
+// making it a no-op avoids "already registered" notices.
+public static function register_category() {
+    // No-op: `site` is registered upstream.
+}
+```
+
+`register_abilities()` keeps its normal behavior. Ability slugs are still product-namespaced (`jetpack-backup/get-backup-overview`) — the category and the slug prefix are independent.
+
 The subclass just needs the three abstract getters plus execute + permission callbacks.
 
 ## Plugin-context template
@@ -110,6 +137,10 @@ class <Name>_Abilities extends Registrar {
 						'destructive' => false,
 						'idempotent'  => true,
 					),
+					'mcp'          => array(
+						'public' => true,
+						'type'   => 'tool',
+					),
 					'show_in_rest' => true,
 				),
 			),
@@ -152,6 +183,10 @@ class <Name>_Abilities extends Registrar {
 						'destructive' => false,
 						'idempotent'  => true,
 					),
+					'mcp'          => array(
+						'public' => true,
+						'type'   => 'tool',
+					),
 					'show_in_rest' => true,
 				),
 			),