← All explainers
A field guide to installable AI capabilities

AI plugins are capability kits you can install.

A plugin packages the guidance, connections, and interface an AI needs to do a particular kind of work—then makes that capability discoverable and portable.

01 · Mental model

A shipping crate for a capability.

The package

The label identifies what it is. Inside, instructions explain the work, adapters connect equipment, and a control panel may expose the result.

The reality

A plugin can bundle skills, an MCP server connection, and optional UI behind one installable identity.

02 · Architecture

One container, three kinds of capability.

GUIDANCESkillsWorkflow + expertise
ACTIONMCP serverTools + auth + data
INTERFACEOptional UIInspect + edit + confirm

The manifest is the label. It gives the package an identity and points the host to what is inside.

03 · Runtime journey

Discover, install, invoke, act.

01DiscoverFind a capability in a directory.
02InstallAdd the plugin to the AI host.
03AskThe user gives a matching task.
04GuideA skill can shape the workflow.
05ActMCP tools reach external systems.
06ShowOptional UI makes results tangible.

Not every plugin uses every layer. The smallest useful package is usually the best starting point.

04 · Build the shape

What does your plugin need?

SKILLS + MCP

Guided, connected workflow

Instructions coordinate a repeatable method while tools read or change external systems.

  • Knows how to work
  • Can take external action
05 · Package anatomy

The manifest connects the pieces.

.codex-plugin/plugin.jsonRequired identity and package metadata
skills/Reusable workflow packages
.app.jsonRegistered remote MCP connection
.mcp.jsonBundled MCP server configuration
assets/Optional icons and supporting files
06 · Pick the minimum

Three useful plugin shapes.

METHOD

Skills only

Use when existing tools are enough, but the agent needs a reliable procedure or specialist guidance.

CAPABILITY

MCP only

Use when the host needs new tools or data access and the operation is already self-explanatory.

ORCHESTRATED WORK

Skills + MCP

Use when a workflow must guide when and how a set of external tools should be used.

07 · Trust boundary

Installation grants possibility, not permissionlessness.

AUTHWho is connected?

Credentials determine which account and data the tools can reach.

TOOLSWhat can act?

Tool schemas define the operations exposed to the model.

CONSENTWhat needs confirmation?

High-impact actions should stay legible and intentional.

OUTPUTWhat returns?

Structured results and UI help people inspect the outcome.

08 · Build and publish

Start with the smallest coherent promise.

Name one capability.Describe the outcome a person installs the plugin to achieve.
Choose the shape.Add skills, MCP, or both; add UI only when interaction improves understanding.
Declare the package.Create the manifest and connect each included component.
Test trust boundaries.Verify authentication, confirmations, tool errors, and empty states.
Distribute deliberately.Keep it local, share through a repository, or publish to a supported directory.
09 · Keep this model

Skill teaches. MCP reaches. UI reveals. Plugin ships.

TEACH

Skill

Encodes the method and judgment for a repeatable workflow.

REACH

MCP

Connects the AI to tools, services, authentication, and structured results.

SHIP

Plugin

Bundles the capability behind an identity people can discover and install.