Ship Agent Plugins with Python packages.

Documentation · PyPI · Agent Plugins format

Agent Plugins gives reusable Agent Skills and Model Context Protocol (MCP) servers one package structure that compatible clients can discover consistently. A plugin.json manifest identifies the format, fixed locations expose its portable components, and namespaced client extensions preserve client-specific behavior. Authors maintain one plugin layout, and each client loads the parts it supports.

The specification defines that directory boundary. agent-plugins carries the complete plugin through Python packaging beside the library it extends. Regular Python wheels and source distributions can contain the manifest, skills, MCP configuration, and extension files. Installing the distribution makes its matching Agent Plugin available through Python metadata. Editable installs point discovery at the authored directory.

The library and plugin share one release boundary. Teams can update library behavior, skills, MCP configuration, and client extensions together, evaluate the resulting integration against that build, then version, publish, install, and roll them back as one unit. Users and agents install one package, and compatible clients can discover the plugin for that installed library version immediately.

Quickstart

Keep the plugin directory beside its Python package:

my-project/
├── plugin.json
├── skills/
│   └── use-my-project/
│       └── SKILL.md
└── packages/
    └── python/
        ├── pyproject.toml
        └── src/
            └── my_project/
                └── __init__.py

Create plugin.json:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-project"
}

Create skills/use-my-project/SKILL.md:

---
name: use-my-project
description: Use my-project to process project records.
---

# Use my-project

Import `my_project` and call its public API.

Create an empty packages/python/src/my_project/__init__.py, then configure the Python project:

Wrap the uv build backend in packages/python/pyproject.toml:

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.10"

[build-system]
requires = ["agent-plugins", "uv_build"]
build-backend = "agent_plugins.build.uv_build"

[tool.agent-plugins]
root = "../.."

With the uv package manager installed, preview the selected files, build the package, install the wheel in a temporary environment, and locate its Agent Plugin:

uv run --with agent-plugins agent-plugins plan packages/python
uv build packages/python --out-dir dist
uv run \
  --with agent-plugins \
  --with dist/my_project-0.1.0-py3-none-any.whl \
  agent-plugins locate my-project

/path/to/site-packages/my_project-0.1.0.agent-plugin

The printed Agent Plugin directory and the importable library came from the same wheel and share its distribution version.

The complete quickstart includes the Python package and Agent Skill files needed for a runnable project.

Inspect installed plugins

Add agent-plugins to runtime dependencies when Python code calls the inspection API:

[project]
dependencies = ["agent-plugins"]

import agent_plugins as ap

plugin = ap.locate("my-project")

print(plugin.manifest.name)
print(plugin.tree())

for skill in plugin.skills:
    print(skill.tree(max_depth=2))
    print(skill.body)

if plugin.mcp is not None:
    for name, server in plugin.mcp.servers.items():
        print(name, server)

locate() accepts the Python distribution name used by pip. plugin.manifest.name is a separate Agent Plugin identity.

Code-mode agents that can execute Python can use the installed distribution as their plugin source. Through the same API, they can inspect the manifest and MCP configuration, traverse plugin.skills, read skill instructions, and open client extension files through native Path operations. See Inspect installed plugins.

Core model

The build plan selects the plugin files and checks their paths before the backend packages them beside the library. Manifest, MCP, and skill-document content is read on first access through the inspection API and cached for that handle.

Related work

TanStack Intent versions Agent Skills with npm library releases and lets agents discover them from installed dependencies. agent-plugins applies that package-manager principle to Python and carries the broader Agent Plugins format: the manifest, optional skills and MCP configuration, and client extension files.

Development

development_docs/ covers contributor setup, architecture, testing, packaging, documentation, and releases. Serve the docs through Portless:

pnpm --dir docs dev

The main checkout uses https://docs.agent-plugins.localhost. Linked worktrees receive a branch-prefixed subdomain.

License

Licensed under the Apache License 2.0.