Add docs about Yoast Abilities

docs/features/yoast-abilities-api/overview.md

@@ -0,0 +1,42 @@
+---
+id: overview
+title: "Yoast SEO Abilities API"
+sidebar_label: Overview
+description: This documentation explains what is the Abilities API and how Yoast SEO integrates with it.
+---
+This documentation explains what is the Abilities API and how [Yoast SEO](https://yoast.com/product/yoast-seo-wordpress/) integrates with it.
+
+## What is the Abilities API?
+Abilities API is a standardized way for plugins to expose what they can do, [introduced in WordPress 6.9](https://developer.wordpress.org/news/2025/11/introducing-the-wordpress-abilities-api/). It allows plugins to do so by providing:
+* A **registry** where plugins declare their capabilities/features/functionalities (also known as **abilities**) with structured input and output schemas.
+* A **central REST discovery endpoint** (`/wp-json/wp-abilities/v1/abilities`) where any client/plugin can list everything that's available.
+* A **standardized execution endpoint** (`/run`) to invoke any registered ability.
+* **Permission checks** for every ability, so access control is consistent.
+
+Once an ability is registered, it is discoverable and executable from PHP, JavaScript, and the REST API. That way, AI agents (and other third-party systems) can use that ability for their purproses.
+
+## Yoast SEO Abilities API
+The abilities that Yoast SEO is currently registering are:
+
+* [Recent Posts' SEO Ability](recent-posts-seo-ability.md) - Gets the SEO scores for the most recently modified posts
+* [Recent Posts' Readability Ability](recent-posts-readability-ability.md) - Gets the Readability scores for the most recently modified posts
+* [Recent Posts' Inclusive Language Ability](recent-posts-inclusive-language-ability.md) - Gets the Inclusive Language scores for the most recently modified posts
+
+Those abilities can also be discovered at `/wp-json/wp-abilities/v1/abilities?category=yoast-seo` along with their most relevant information.
+
+## Use cases for the Yoast SEO Abilities API
+
+### AI agents
+Assuming that an AI agent is connected to a WordPress-enabled MCP site (details on how one can do that, on [this helpful tutorial](https://developer.wordpress.org/news/2026/02/from-abilities-to-ai-agents-introducing-the-wordpress-mcp-adapter) from the WP Core team ) with Yoast SEO active, it can then discover the above abilities and answer questions like:
+* _"Take a look at the latest posts of my website and give me a report of the analysis of their SEO scores. Do you see a clear pattern in the subjects of the best performing ones?"_
+* _"Do you see the readability of my recent content going upwards or downwards?"_
+* _"I want to know if I have content on my site that uses non-inclusive language. If there's indeed not inclusive language in my content, do you see a correlation between the subjects covered?"_
+
+That way, Yoast SEO exposes the results of its analyses to authenticated AI agents, enabling users to use AI capabilities to easily navigate through useful SEO data of their website and create reports, map out plans and perform SEO-related actions accordingly.
+
+### Third-party code
+For plugins interested in building features on top of Yoast SEO Analyses, a more traditional way to consume the Yoast SEO Abilities API would be to use the new WP REST API endpoints. This allows information about a website's recent posts to be reliably retrieved in a structured way.
+
+## Prerequisites
+* WordPress version should over v6.9.
+* [Indexables](/features/indexables/functional-specification.md) should be enabled and fully built.

docs/features/yoast-abilities-api/recent-posts-inclusive-language-ability.md

@@ -0,0 +1,131 @@
+---
+id: recent-posts-inclusive-language-ability
+title: "Yoast SEO Abilities API - Recent Posts's Inclusive Language Ability"
+sidebar_label: Recent Posts's Inclusive Language Ability
+description: This documentation explains what is the Recent Posts's Inclusive Language Ability.
+---
+
+The **Recent Posts's Inclusive Language Ability** returns the results of the Inclusive Language analysis of the most recently modified posts.
+
+It receives the number of recent posts that the ability consumer wants to learn the inclusive language scores for and outputs the results of the Inclusive Language analysis along with the title for each of those posts.
+
+## Description
+If you send a _GET_ request to `/wp-json/wp-abilities/v1/abilities` with Yoast SEO enabled, along with the rest of the abilities that are registered in your website, you will find the description of the Recent Posts's Inclusive Language Ability:
+```
+    {
+        "name": "yoast-seo/get-inclusive-language-scores",
+        "label": "Get Inclusive Language Scores",
+        "description": "Get the inclusive language scores for the most recently modified posts.",
+        "category": "yoast-seo",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "number_of_posts": {
+                    "type": "integer",
+                    "description": "The number of recently modified posts to retrieve scores for. Defaults to 10.",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "default": 10
+                }
+            }
+        },
+        "output_schema": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "title": {
+                        "type": "string",
+                        "description": "The post title."
+                    },
+                    "score": {
+                        "type": "string",
+                        "enum": [
+                            "na",
+                            "bad",
+                            "ok",
+                            "good"
+                        ],
+                        "description": "The score slug."
+                    },
+                    "label": {
+                        "type": "string",
+                        "description": "A human-readable label for the score."
+                    }
+                }
+            }
+        },
+        "meta": {
+            "annotations": {
+                "readonly": true,
+                "destructive": false,
+                "idempotent": true
+            },
+            "show_in_rest": true,
+            "mcp": {
+                "public": true
+            }
+        },
+        "_links": {
+            "self": [
+                {
+                    "href": "http://test.local/wp-json/wp-abilities/v1/abilities/yoast-seo/get-inclusive-language-scores",
+                    "targetHints": {
+                        "allow": [
+                            "GET"
+                        ]
+                    }
+                }
+            ],
+            "collection": [
+                {
+                    "href": "http://test.local/wp-json/wp-abilities/v1/abilities"
+                }
+            ],
+            "wp:action-run": [
+                {
+                    "href": "http://test.local/wp-json/wp-abilities/v1/abilities/yoast-seo/get-inclusive-language-scores/run"
+                }
+            ]
+        }
+    }
+```
+The most interesting things that this description shows, along with other information that describe how this ability is meant to be used, are:
+* the `description` which describes briefly what the ability does
+* the `input_schema` that describes what argument the ability expects and that's the number of recent posts we want
+* the `output_schema` that describes what the ability is expected to return as a result and that's an array of objects, where for each post the object will contain its title and inclusive language score
+
+## Usage
+To use the Recent Posts's Inclusive Language Ability, a _GET_ request to `/wp-json/wp-abilities/v1/abilities/yoast-seo/get-inclusive-language-scores/run?input[number_of_posts]=3` is sent, for the inclusive language scores of the latest 3 posts.
+
+Doing so in a website might yield the following result:
+```
+[
+    {
+        "title": "How to Store Fresh Herbs So They Last Longer",
+        "score": "bad",
+        "label": "Needs improvement"
+    },
+    {
+        "title": "5 Easy Recipes for Cauliflower",
+        "score": "good",
+        "label": "Good"
+    },
+    {
+        "title": "10 Common Mistakes when Making Homemade Bread",
+        "score": "na",
+        "label": "Not available"
+    }
+]
+```
+
+## How to disable it programmatically?
+There's a way to disable the Recent Posts's Inclusive Language Ability programmatically and that's by using the WP native `wp_abilities_api_init` action, like so:
+```
+add_action( 'wp_abilities_api_init', function() { 
+        if ( wp_has_ability( 'yoast-seo/get-inclusive-language-scores' ) ) {
+            wp_unregister_ability( 'yoast-seo/get-inclusive-language-scores' );
+        }
+    }, 20
+); // Run after Yoast SEO registers at default priority 10
+```

docs/features/yoast-abilities-api/recent-posts-readability-ability.md

@@ -0,0 +1,131 @@
+---
+id: recent-posts-readability-ability
+title: "Yoast SEO Abilities API - Recent Posts's Readability Ability"
+sidebar_label: Recent Posts's Readability Ability
+description: This documentation explains what is the Recent Posts's Readability Ability.
+---
+
+The **Recent Posts's Readability Ability** returns the results of the readability analysis of the most recently modified posts.
+
+It receives the number of recent posts that the ability consumer wants to learn the readability scores for and outputs the results of the Readability analysis along with the title for each of those posts.
+
+## Description
+If you send a _GET_ request to `/wp-json/wp-abilities/v1/abilities` with Yoast SEO enabled, along with the rest of the abilities that are registered in your website, you will find the description of the Recent Posts's Readability Ability:
+```
+    {
+        "name": "yoast-seo/get-readability-scores",
+        "label": "Get Readability Scores",
+        "description": "Get the readability scores for the most recently modified posts.",
+        "category": "yoast-seo",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "number_of_posts": {
+                    "type": "integer",
+                    "description": "The number of recently modified posts to retrieve scores for. Defaults to 10.",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "default": 10
+                }
+            }
+        },
+        "output_schema": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "title": {
+                        "type": "string",
+                        "description": "The post title."
+                    },
+                    "score": {
+                        "type": "string",
+                        "enum": [
+                            "na",
+                            "bad",
+                            "ok",
+                            "good"
+                        ],
+                        "description": "The score slug."
+                    },
+                    "label": {
+                        "type": "string",
+                        "description": "A human-readable label for the score."
+                    }
+                }
+            }
+        },
+        "meta": {
+            "annotations": {
+                "readonly": true,
+                "destructive": false,
+                "idempotent": true
+            },
+            "show_in_rest": true,
+            "mcp": {
+                "public": true
+            }
+        },
+        "_links": {
+            "self": [
+                {
+                    "href": "http://test.local/wp-json/wp-abilities/v1/abilities/yoast-seo/get-readability-scores",
+                    "targetHints": {
+                        "allow": [
+                            "GET"
+                        ]
+                    }
+                }
+            ],
+            "collection": [
+                {
+                    "href": "http://test.local/wp-json/wp-abilities/v1/abilities"
+                }
+            ],
+            "wp:action-run": [
+                {
+                    "href": "http://test.local/wp-json/wp-abilities/v1/abilities/yoast-seo/get-readability-scores/run"
+                }
+            ]
+        }
+    }
+```
+The most interesting things that this description shows, along with other information that describe how this ability is meant to be used, are:
+* the `description` which describes briefly what the ability does
+* the `input_schema` that describes what argument the ability expects and that's the number of recent posts we want
+* the `output_schema` that describes what the ability is expected to return as a result and that's an array of objects, where for each post the object will contain its title and readability score
+
+## Usage
+To use the Recent Posts's Readability Ability, a _GET_ request to `/wp-json/wp-abilities/v1/abilities/yoast-seo/get-readability-scores/run?input[number_of_posts]=3` is sent, for the readability scores of the latest 3 posts.
+
+Doing so in a website might yield the following result:
+```
+[
+    {
+        "title": "How to Meal Prep for the Entire Week in 2 Hours",
+        "score": "good",
+        "label": "Good"
+    },
+    {
+        "title": "The Beginner’s Guide to Cooking with Cast Iron",
+        "score": "good",
+        "label": "Good"
+    },
+    {
+        "title": "Things to Avoid when on a Protein-Based Diet",
+        "score": "ok",
+        "label": "OK"
+    }
+]
+```
+
+## How to disable it programmatically?
+There's a way to disable the Recent Posts's Readability Ability programmatically and that's by using the WP native `wp_abilities_api_init` action, like so:
+```
+add_action( 'wp_abilities_api_init', function() { 
+        if ( wp_has_ability( 'yoast-seo/get-readability-scores' ) ) {
+            wp_unregister_ability( 'yoast-seo/get-readability-scores' );
+        }
+    }, 20
+); // Run after Yoast SEO registers at default priority 10
+```