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.
Use a build-backend adapter when agent-plugins owns the Python build path. When another tool already produced the wheel, attach the configured plugin as a separate artifact step. The command and Python API rewrite the input after the complete attached artifact succeeds. Pass --output-dir or output_dir to preserve it.
agent-plugins attach-wheel dist/example-1.0.0-py3-none-any.whl --project .
import agent_plugins as ap
result = ap.attach_wheel("dist/example-1.0.0-py3-none-any.whl")
print(result.output)
Both paths use the same build plan and wheel writer. See Attach a prebuilt wheel for output copies, result fields, reruns, and signature handling.
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 a project or installation
Add agent-plugins to runtime dependencies when Python code calls the inspection API:
[project]
dependencies = ["agent-plugins"]
import agent_plugins as ap
source = ap.Plugin.from_project("packages/python")
installed = ap.locate("my-project")
skill = source.skill("use-my-project")
print(source.manifest.name)
print(skill.source)
print(skill.file("SKILL.md"))
if installed.mcp is not None:
for name, server in installed.mcp.servers.items():
print(name, server)
Plugin.from_project() exposes exactly the files selected by [tool.agent-plugins]. After installing a build produced from that selection, locate() exposes the same plugin-relative inventory. Plugin(path) remains the directory-tree constructor for every current file below a plugin root.
skill.source returns the complete cached SKILL.md text. skill.file() checks that a resource belongs to the selected inventory before returning its path.
locate() accepts the Python distribution name used by pip. installed.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 a build-backend adapter or attach_wheel() 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.