Ship Agent Plugins with Python packages.

Documentation · PyPI · Agent Plugins format

agent-plugins ships a Python library and its agent integrations in one package. An agent with Python execution can read its packaged instructions, then use the library in the same environment. Library code, skills, tool configuration, and resources share one release.

The Agent Plugins format defines the directory: a manifest, Agent Skills for instructions and resources, Model Context Protocol (MCP) server configuration for tools, and client extensions. This library packages that directory and makes it discoverable through Python metadata. Agent clients choose which components to activate.

Read the bundled guidance

Run agent-plugins without arguments to read its own installed plugin:

uvx agent-plugins

The output contains two version-matched skills. agent-plugins explains how to read instructions from Python packages that already ship an Agent Plugin. package-agent-plugin explains how to add Agent Plugin packaging to a Python project.

Package your plugin

Keep plugin.json and skills/ beside your code. For a project using the uv build backend, configure pyproject.toml:

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

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

Build with the uv package manager:

uv build

The quickstart creates a complete project, builds it, and locates the installed plugin. Use the Hatchling adapter for Hatchling projects, or attach a prebuilt wheel when another tool owns the build:

agent-plugins attach-wheel dist/my_project-0.1.0-py3-none-any.whl --project .

Attachment updates the wheel in place. Pass --output-dir to preserve the input.

Inspect an installed plugin

Load the complete version-matched guidance shipped by a package:

uvx --with my-package agent-plugins read my-package

The first my-package tells uv which distribution to install. The second identifies the installed Agent Plugin to read.

Use the Python API when the package is already installed in the current environment:

import agent_plugins as ap

print(ap.read("agent-plugins"))
print(ap.read("agent-plugins", skill="package-agent-plugin"))

read() returns a briefing for the same-name skill by default. Pass skill= for another workflow. The CLI reads all packaged skills unless --skill is provided. uvx uses an isolated tool environment, so read through the target interpreter when working with an existing installation.

Pass your library's distribution name to locate() to inspect its plugin. Use Plugin.from_project() to inspect the selected source files before building.

Documentation

• Get started: package, install, and locate a plugin.
• How packaging works: wheels, source distributions, and editable installs.
• Integrate: read skills, inspect files, and resolve MCP configuration.
• Python API · CLI · Configuration

Packaging lifecycle

Development

See development_docs/ for setup, architecture, checks, and releases. Serve the documentation locally with pnpm --dir docs dev.

License

Apache-2.0.