Agent Pilot

Agent Pilot lets WordPress authors create Agent Skills in the block editor and publish them through the Agent Skills Discovery via Well-Known URIs v0.2.0 draft and Agent Plugins. Skills are standalone instructions discovered through the well-known index while plugins are packages that compose Skills and optional MCP server configuration.

Requirements

• WordPress 6.6 or newer, or 6.9 or newer for the MCP server, which needs the Abilities API.
• PHP 7.4 or newer.
• PHP zip extension for archive generation.
• Update Pilot is used for automatic plugin updates. Agent Pilot shows an admin notice when Update Pilot is unavailable.

Installing Agent Skills

Publish one or more Agent Skills, then install them with the skills CLI. Replace https://example.com with the WordPress site URL.

# Inspect available skills.
npx skills add https://example.com --list

# Install selected skills in the current project.
npx skills add https://example.com

# Install skills globally instead of in the current project.
npx skills add https://example.com --global

The CLI reads:

https://example.com/.well-known/agent-skills/index.json

It prompts for skills to install unless options such as --agent, --skill, or --yes are supplied.

Update installed skills after changing their WordPress content:

# Update all installed project skills.
npx skills update --project

# Update all installed global skills.
npx skills update --global

# Update one skill by name.
npx skills update my-skill

Authoring Skills

Agent Skills are normal WordPress posts with a dedicated post type:

• Post type: agent_skill.
• Public permalink prefix: /agent-skill/{name}.
• Plain permalink fallback: ?agent-skill={name}.
• Supports title, editor, excerpt, author, revisions, and custom fields.

The editor uses a locked agent-pilot/agent-skill wrapper block. New skills start with one instruction paragraph inside that wrapper.

The skill front matter fields are edited inside the Agent Skill block:

• name is saved as the post slug.
• description is saved as the native post excerpt.
• compatibility is saved as agent_pilot__compatibility post meta.

The editor marks the name, description, and instructions as required. Descriptions are limited to 1024 characters, and compatibility notes are limited to 500 characters.

Skill instructions can use the blocks that Agent Pilot can convert to Markdown:

• Paragraphs, headings, lists, code, preformatted text, quotes, separators, and images.
• Image blocks export as Markdown images using the saved image URL and alt text.
• Agent Pilot resource blocks: Reference, Script, and Asset.

Use the Add Reference, Add Script, and Add File buttons below the instructions to append resource blocks. Once a resource filename is configured, the resource panel header shows the path to use in instructions, such as references/guide.md, scripts/build.sh, or assets/diagram.png.

Resources

Resources are stored in the skill post content, packaged into the skill ZIP, and listed in SKILL.md. Resource contents are not inlined into SKILL.md. Resource filenames are normalized with the WordPress sanitize_file_name() helper during packaging, so directory separators and path traversal sequences never reach the generated archive.

References

Reference blocks publish supporting documents under references/.

• Filenames use lowercase letters and hyphens.
• Formats are .md and .html.
• New references default to .md.
• Custom reference content can be authored with nested blocks.
• A reference can also use an existing post, page, or REST-searchable custom post type selected through the combobox.
• When existing content is selected, it takes precedence over the custom reference content. The custom content remains saved and is used again if the selection is removed.
• Markdown references convert supported blocks to Markdown. HTML references publish rendered block HTML.

Scripts

Script blocks publish executable or helper text files under scripts/.

• Filenames may contain ASCII letters, numbers, dots, underscores, and hyphens.
• Filenames must begin with a letter or number and cannot contain slashes.
• The editor shows the scripts/ prefix without storing it in the filename.
• Script content is edited with bundled CodeMirror syntax highlighting based on the filename extension.

Assets

Asset blocks publish Media Library attachment bytes under assets/.

• Assets require an attachment.
• The selected attachment filename is saved as the asset filename.
• The editor shows the assets/ prefix without storing it in the filename.
• Replacing a selected asset happens from the block toolbar.

Generated Output

Agent Pilot generates SKILL.md from:

• Front matter:
  • name from the post slug.
  • description from the post excerpt.
  • compatibility from agent_pilot__compatibility.
  • Values are emitted as plain YAML scalars and quoted only when required.
• Body:
  • A top-level heading from the post title.
  • Supported instruction blocks converted to Markdown.
  • References, Assets, and Scripts sections listing packaged resource paths when valid resources exist.

The editor sidebar includes an Agent Skill panel with links to the generated SKILL.md file and SKILL.zip archive after the post has a usable skill URL.

On human-facing single skill pages, the Agent Skill block renders the generated Markdown inside an escaped <pre> block so visitors can inspect the exact output.

Discovery and Routing

Only published skills appear in public discovery. Draft and private skills stay hidden from the public index and public file routes, while normal authenticated WordPress previews still work.

The discovery index is served at:

/.well-known/agent-skills/index.json

Each index entry currently publishes an archive:

• type: archive
• url: /agent-skill/{name}/skill.zip
• digest: SHA-256 digest of the served ZIP bytes
• files: contains SKILL.md for compatibility with clients that require a non-empty file list

Pretty permalink artifact routes:

/agent-skill/{name}/skill.md
/agent-skill/{name}/skill.zip

Plain permalink artifact routes:

?agent-skill={name}&agent_pilot_skill_format=skill.md
?agent-skill={name}&agent_pilot_skill_format=skill.zip

The generated ZIP represents the skill directory contents. Agent Pilot writes SKILL.md at the archive root, with valid supporting files under root-level references/, scripts/, and assets/ directories. Archive entries reuse the skill last modified time, so an unchanged skill regenerates into byte-identical archives with a stable digest (on PHP 8.0 or newer).

Discovery index and artifact responses support GET and HEAD, include CORS and X-Content-Type-Options headers, and use ETags. WordPress front-end responses advertise the discovery index with an RFC 8288 Link header, while REST API responses do not include it:

Link: <https://example.com/.well-known/agent-skills/index.json>; rel="agent-skills"

The raw artifact rewrite only accepts a one-segment format suffix such as skill.md or skill.zip, so nested paths such as /agent-skill/{name}/references/guide.md stay with WordPress. Other one-segment suffixes under a skill permalink, including /feed and /embed, are claimed by the same rewrite and resolve to the single skill view instead of the WordPress feed and embed endpoints.

Authoring Agent Plugins

Create an Agent Plugin post, enter its manifest details in the top-level block, then insert Plugin Skill and MCP Server child blocks. Skills are stored by post ID and are included live: changing a selected skill changes the next generated plugin archive without re-saving the plugin.

The manifest supports name (the post slug), description (the excerpt), author, license, and extensions. A package needs at least one selected skill or valid MCP server. Published packages may only select published skills. A Plugin Skill block with nothing selected yet is ignored rather than treated as an error, so an empty block left open in the editor never breaks the generated artifacts; a block pointing at a post that is not an Agent Skill still fails validation.

Each MCP server uses a name plus a raw JSON object edited with JSON syntax highlighting. Agent Pilot preserves the object without validating its transport or schema; authors are responsible for supplying configuration that their target MCP client accepts. MCP definitions are public package contents—never put credentials or tokens in them.

Agent Plugin artifacts are available for a valid published plugin at:

/agent-plugin/{name}/plugin.json
/agent-plugin/{name}/mcp.json
/agent-plugin/{name}/plugin.zip

The editor sidebar includes an Agent Plugin panel linking to every routed artifact: plugin.json, mcp.json when available, and plugin.zip.

With plain permalinks, use ?agent-plugin={name}&agent_pilot_plugin_format=plugin.json (or mcp.json / plugin.zip). Draft previews require permission to read every referenced post and are never publicly cacheable. The ZIP is a distribution convenience: the specification defines the extracted directory layout (plugin.json, skills/{name}/…, and optional mcp.json), not an installation or distribution protocol.

MCP Server

Agent Pilot can also serve this site's WordPress Abilities as MCP tools, so that an agent client can call site functionality directly instead of only reading published instructions. This is separate from the MCP server definitions an Agent Plugin carries: those point a client at some other server, while this one is served by WordPress itself.

The server is opt-in. Enable it under Settings → Agent Pilot, where the endpoint URL is also shown:

https://example.com/wp-json/agent-pilot/v1/mcp

Requires WordPress 6.9 or newer for the Abilities API. Agent Pilot shows a notice on the settings screen when the API is unavailable.

Disabling MCP abilities

Under Settings → Agent Pilot → Abilities, select the abilities to exclude and save. Selected abilities disappear from tools/list and cannot be called by name through tools/call, even by a client that previously discovered them. Clear a checkbox to restore the ability's normal mapping. No abilities are disabled by default.

The list shows abilities eligible for MCP mapping and any saved exclusions whose provider is currently unavailable. Exclusions apply after the agent_pilot__mcp_abilities query filter, so customizing the query does not re-enable a disabled ability. This setting controls Agent Pilot's tool mapping; the abilities and REST endpoints remain available through their normal interfaces.

The setting is stored per site as agent_pilot__mcp_disabled_abilities, an array of ability names such as agent-pilot/rest-call. Administrators can also update it through /wp/v2/settings; send an empty array to clear all exclusions.

Built-in REST ability

Agent Pilot registers agent-pilot/rest-call on WordPress 6.9 or newer and exposes it as the agent-pilot-rest-call MCP tool. Enable the MCP server to let authenticated clients discover and call this site's REST endpoints without registering an ability for each route. The ability is also compatible with the official WordPress MCP Adapter.

Pass method, route (an internal path without a query string), and optional params:

{ "method": "GET", "route": "/wp/v2/posts", "params": { "per_page": 5 } }

Supported methods are GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS. Parameters become query parameters for GET, HEAD, and DELETE, and body parameters for other methods. Calls run internally as the authenticated WordPress user. The ability's permission callback matches the REST endpoint, prepares its URL parameters, defaults, and sanitized input, then checks the endpoint's permissions before execution. Permission denials are ability errors; the endpoint callback is never executed by the permission check. Normal REST dispatch checks permissions again when executing an allowed call. Results contain status, headers, and data, including native REST validation and routing errors such as 400 and 404.

OPTIONS <route> returns one route's methods and parameter schema and is the cheap way to learn an endpoint. GET / returns the whole index, which is around 230 KB on a stock site because it carries every route's args; narrowing it with _fields is what makes it usable, and _fields=namespaces answers in about 140 bytes. Route keys in the index are the registered patterns rather than templates, so /wp/v2/posts/(?P<id>[\d]+) is called as /wp/v2/posts/123.

Because requests are dispatched internally rather than served over HTTP, they never pass through the rest_post_dispatch filters. Agent Pilot applies the two core behaviors that shape a response — _fields filtering and the Allow header — and resolves _embed from the request rather than from the query string, so those work as they do over HTTP. Anything else a site hooks to rest_post_dispatch for its HTTP responses does not run here.

Because this single tool can modify and delete content, it requires wp:write for OAuth callers, including when making a GET request. It is annotated as potentially destructive and non-idempotent. The MCP server's existing ability query and registration filters also apply to this built-in ability.