What is an Agent Plugin?

An agent client is an application that loads agent instructions and integrations. Agent Skills provide reusable instructions and resources. Model Context Protocol (MCP) servers connect agents to tools and services. Both can be reused across clients, yet each client's native plugin format may place and describe them differently.

Agent Plugins defines one small package contract: a plugin.json manifest, fixed locations for skills and MCP server configuration, and namespaced client extensions. Plugin authors maintain one structure. Compatible clients discover the same structure and load the parts they support.

The specification leaves distribution and installation to clients. agent-plugins carries that directory through Python packaging beside the library it extends. A regular wheel installs the code and plugin together. An editable wheel points discovery at the authored plugin directory. The Python API and command-line interface (CLI) locate either form through the installed distribution metadata.

A wheel is an installable Python archive. A source distribution carries source files for a build frontend to turn into a wheel.

One release boundary

The built distribution captures the library code and selected Agent Plugin files from the same source revision. Run library tests and evaluate the plugin against that build, then publish one distribution version. Installing another version replaces both packaged surfaces together.

For users and agents, install the Python distribution once. The Agent Plugin is immediately available for compatible clients to discover. A code-mode agent can call agent_plugins.locate() and inspect the same packaged manifest, skills, MCP configuration, and client extension files through native Python paths.

The lifecycle

flowchart TD
    author[Python project<br/>Library code and Agent Plugin directory] --> plan[Build plan]
    plan --> modes[Regular wheel<br/>Source distribution<br/>Editable wheel]
    modes --> install[Installed library, Agent Plugin, and marker]
    install --> discovery[Marker-based discovery]
    discovery --> handle[Plugin handle and file inventory]
    handle --> documents[Lazy manifest, skill, and MCP access]

The authored plugin directory is the directory you maintain. Its root contains plugin.json.

The build plan is an ordered set of source-to-target file mappings. agent-plugins plan shows this selection before a build.

The agent_plugins.json marker lives inside the Python distribution metadata. It records the installed plugin root and exact file inventory.

A Plugin handle is the filesystem-backed Python object returned by agent_plugins.locate() or created directly with agent_plugins.Plugin(path).

Plugin contents

A plugin directory has one required file and three optional content surfaces.

Content	Role	Selection
plugin.json	Identifies the Agent Plugin and its schema	Always required
skills/	Contains immediate Agent Skill directories	Complete directory tree
mcp.json	Describes MCP server entries	Included when present
Client extension files	Supplies files owned by a specific agent client	Selected with include patterns

plugin.json.extensions is manifest extension data. It is namespaced JSON inside the manifest. Client extension files are separate files in the plugin directory.

Identities and versions

Several names and versions coexist by design.

Term	Source	Used by
Python distribution name	project.name in pyproject.toml	pip, locate(), and installed()
Plugin name	name in plugin.json	Agent Plugin manifest consumers
Distribution version	project.version	Wheel metadata and installed paths
Plugin version	Optional version in plugin.json	Agent Plugin consumers
Format version	$schema in each JSON document	Document validation

locate() accepts the Python distribution name. The library does not require the distribution name, plugin name, distribution version, and plugin version to match.

Related work

TanStack Intent versions Agent Skills with npm library releases and discovers them from installed dependencies. agent-plugins applies that package-manager pattern to Python and uses the broader Agent Plugins directory as its artifact, including the manifest, optional skills and MCP configuration, and client extension files.

What the library owns

agent-plugins owns file selection, artifact augmentation, installed discovery, filesystem handles, and local document validation.

The agent client owns installation policy, permission prompts, placeholder expansion, MCP process startup, transport connections, and user experience. An accepted MCP server entry describes a configuration. It does not prove that the server executable or endpoint is available.

Document and path validation proves supported structure and containment. Review packaged instructions and executables before installation or activation. Validation does not establish that their behavior is trustworthy.

Continue with Get started to package and locate one Agent Plugin.