# agent-plugins

> Ship Agent Plugins with Python packages.

Release your library, agent instructions, and tool configuration together. One Python install makes the matching plugin available to agent clients.

## Table of Contents

### Start

- [What is an Agent Plugin?](https://peter-gy.github.io/agent-plugins/guide/what-is-an-agent-plugin.md): Ship a Python library and its Agent Plugin in one versioned distribution.
- [Get started](https://peter-gy.github.io/agent-plugins/guide/getting-started.md): Build a Python library with an Agent Skill, install the wheel, and read its instructions from Python.
- [How packaging works](https://peter-gy.github.io/agent-plugins/guide/artifact-lifecycle.md): Follow Agent Plugin files through build planning, wheels, source distributions, editable installs, and discovery.

### Author and package

- [Plugin directory](https://peter-gy.github.io/agent-plugins/guide/plugin-directory.md): Organize the manifest, Agent Skills, MCP configuration, and client extension files in one plugin root.
- [Build backends](https://peter-gy.github.io/agent-plugins/guide/build-backends.md): Add Agent Plugin packaging to uv_build, Hatchling, or another compatible Python build backend.
- [Attach a prebuilt wheel](https://peter-gy.github.io/agent-plugins/guide/attach-wheel.md): Add the configured Agent Plugin to a wheel produced by another build tool.
- [Editable installs](https://peter-gy.github.io/agent-plugins/guide/editable-installs.md): Understand how an editable agent_plugins.json marker tracks an authored plugin directory.
- [Verify a package](https://peter-gy.github.io/agent-plugins/guide/verify-package.md): Check file selection, document access, wheel contents, source rebuilds, and editable discovery before publishing.

### Integrate

- [Agent Skills](https://peter-gy.github.io/agent-plugins/integrations/agent-skills.md): Package Agent Skill directories and inspect their files and source text.
- [MCP servers](https://peter-gy.github.io/agent-plugins/integrations/mcp-servers.md): Package and inspect stdio, Streamable HTTP, and legacy SSE server configuration.
- [Client extension files](https://peter-gy.github.io/agent-plugins/integrations/client-extensions.md): Select client-owned files and distinguish them from extension data in plugin.json.

### Inspect

- [Inspect an authored project](https://peter-gy.github.io/agent-plugins/guide/inspect-project.md): Load the exact Agent Plugin selected by a Python project's build plan.
- [Inspect installed plugins](https://peter-gy.github.io/agent-plugins/guide/inspect-installed.md): Locate Agent Plugins by Python distribution name and inspect their selected files and documents.
- [Validation and caching](https://peter-gy.github.io/agent-plugins/guide/validation.md): Understand file-plan checks, lazy document validation, non-fatal issues, and refresh behavior.

### Reference

- [Python API reference](https://peter-gy.github.io/agent-plugins/reference/python-api.md): Reference the complete public API for build planning, wheel attachment, discovery, filesystem handles, documents, values, and diagnostics.
- [CLI reference](https://peter-gy.github.io/agent-plugins/reference/cli.md): Reference agent-plugins read, plan, attach-wheel, locate, and list commands, output formats, and exit statuses.
- [pyproject.toml reference](https://peter-gy.github.io/agent-plugins/reference/pyproject.md): Configure the authored plugin root and additional file selection.
- [plugin.json reference](https://peter-gy.github.io/agent-plugins/reference/plugin-json.md): Reference the Agent Plugins 1.0.0 manifest fields, normalized values, and validation behavior.
- [mcp.json reference](https://peter-gy.github.io/agent-plugins/reference/mcp-json.md): Reference MCP configuration fields, transport values, path rules, URL rules, and validation outcomes.
- [Errors and issues](https://peter-gy.github.io/agent-plugins/reference/errors.md): Handle AgentPluginError, ValidationError, and non-fatal ValidationIssue values.
- [Troubleshooting](https://peter-gy.github.io/agent-plugins/troubleshooting.md): Recover from build-plan, wheel-attachment, installed discovery, document, and editable-install failures.

### Other

- [agent-plugins](https://peter-gy.github.io/agent-plugins/index.md): Ship Agent Plugins with Python packages as one synchronized release.