> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxicore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# What abilities are and how they work in Maxi AI Core

> Abilities are permission-gated MCP operations that AI agents call on your site. Each call returns a standard response and requires a WordPress capability.

Abilities are the building blocks of everything an AI agent can do in Maxi AI Core. Each ability is a discrete operation — like creating a post, listing products, or generating an image — that is capability-checked, audit-logged, and optionally governed by configurable rules. Agents call abilities through the MCP adapter, and every response follows the same predictable shape regardless of which ability was called.

## Response format

Every ability call returns a consistent JSON envelope:

```json theme={null}
{
  "success": true,
  "data": { "..." : "..." },
  "error": null
}
```

When an ability fails, `success` is `false`, `data` may be empty or contain diagnostic fields, and `error` contains a human-readable description. Do not retry a failed ability blindly — read the error and fix the input first.

## Ability groups

Abilities are organized into feature groups. Your license plan determines which groups are available to you.

<CardGroup cols={2}>
  <Card title="Content" icon="file-lines" href="/abilities/content">
    Create, read, update, delete, duplicate, schedule, and search posts, pages, and custom post types.
  </Card>

  <Card title="Taxonomy" icon="tags" href="/abilities/taxonomy">
    Manage categories, tags, and any custom taxonomy — create terms, assign them, or bulk-update across hundreds of posts.
  </Card>

  <Card title="Media" icon="image" href="/abilities/media">
    Upload attachments from URLs or base64, set featured images, regenerate thumbnails, and manage the media library.
  </Card>

  <Card title="Meta" icon="database" href="/abilities/meta">
    Read and write post, term, and user meta — including bulk updates across up to 500 objects in a single call.
  </Card>

  <Card title="AI Generation" icon="wand-magic-sparkles" href="/abilities/ai-text">
    Generate text and images synchronously or via background batch jobs, using OpenAI, Anthropic, OpenRouter, Replicate, BFL, and local providers.
  </Card>

  <Card title="Notes" icon="note-sticky" href="/abilities/notes">
    Persistent knowledge and communication between agents and operators — bug reports, how-tos, and live operator instructions.
  </Card>

  <Card title="System" icon="gear" href="/abilities/system">
    Bootstrap sessions, manage licenses, inspect site info, fetch playbooks, and control ability rules.
  </Card>

  <Card title="WooCommerce" icon="cart-shopping" href="/abilities/woocommerce-products">
    Manage products, variations, orders, coupons, shipping zones, and tax rates. Requires WooCommerce to be active.
  </Card>

  <Card title="Analytics" icon="chart-line" href="/abilities/analytics">
    Query page views, traffic sources, and WooCommerce conversion rates. Requires the Maxi Web Analytics plugin.
  </Card>

  <Card title="Development" icon="terminal" href="/abilities/development">
    Run WP-CLI commands, flush caches, clear transients, and regenerate rewrite rules — with a strict allowlist for safety.
  </Card>
</CardGroup>

## Capability requirements

Every ability declares a required WordPress capability. The server checks this at execution time — not at connection time. If the authenticated user lacks the required capability, the call is rejected.

| Required capability  | Typical use                               |
| -------------------- | ----------------------------------------- |
| `read`               | All read-only list and get abilities      |
| `edit_posts`         | Content creation and updates              |
| `delete_posts`       | Deleting content and attachments          |
| `publish_posts`      | Scheduling content                        |
| `upload_files`       | Uploading media and generating images     |
| `manage_categories`  | Taxonomy term management                  |
| `manage_options`     | Site settings, license, WP-CLI, analytics |
| `edit_products`      | WooCommerce catalog and variations        |
| `manage_woocommerce` | Orders, coupons, shipping, and tax        |
| `is_user_logged_in`  | Notes abilities and session bootstrap     |

<Tip>
  Scope each AI agent to the minimum capabilities it actually needs. A read-only agent needs only `read` and `edit_posts`. An admin-level agent with `manage_options` should only be used when the task genuinely requires it.
</Tip>

## Pro-only abilities

Some abilities are only available on the Pro plan, marked **\[PRO]** in the reference. Examples include `maxi/get-analytics`, `maxi/list-files`, `maxi/read-file`, `maxi/send-email`, and all WooCommerce bulk operations. If you call a Pro ability on a Lite license, you receive a `plan_insufficient` error. See [Licensing](/concepts/licensing) for details on upgrading.

## Ability rules system

Certain abilities carry operator-configurable rules that agents must acknowledge before proceeding. Rules communicate constraints, warnings, or required patterns — for example, a rule on `maxi/bulk-update-products` might describe the exact semantics of bulk-clear operations before an agent uses them.

Rules are delivered **inline** on the first call to an ability, under `_meta._rule` in the response envelope. You do not need a separate prefetch in most cases.

There are two delivery modes:

<AccordionGroup>
  <Accordion title="inline_on_success — descriptive rules">
    The ability executes on the first call. The rule body is attached to the successful response under `_meta._rule`, and the session transitions to acknowledged. Subsequent calls in the same session pass through with no rule attached. All read-only abilities (`get-*`, `list-*`, `search-*`) use this mode.
  </Accordion>

  <Accordion title="reject_first — prescriptive rules">
    The first call is refused with a `rules_not_acknowledged` error, and the rule body is attached to that rejection under `_meta._rule`. Read the rule, then retry the same call — the retry is the acknowledgement, and the gate passes it through. Write and mutation abilities (`create-*`, `update-*`, `delete-*`, `bulk-*`, etc.) use this mode by default.
  </Accordion>
</AccordionGroup>

<Note>
  Ability acknowledgements are scoped to the session. Once you acknowledge a rule, it is not re-delivered until the session ends or an operator updates the rule's content (which bumps its version and triggers re-delivery).
</Note>

If an ability returns `rules_not_installed`, call `maxi/rules-sync` to install the baseline rules shipped with the plugin.

## Full ability reference

For a complete listing of every ability, its parameters, and its capability requirements, see the [Abilities overview](/abilities/overview).