How packaging works

The built distribution is one release boundary for library code and Agent Plugin files. A build-backend adapter can create and augment the artifact in one path. attach_wheel() can augment a wheel that another build tool already produced. Both use selected plugin files from the same source revision: the manifest, any skills and MCP configuration, and included client extension files.

Run library tests and evaluate the Agent Plugin against that artifact before publishing it. Installing or rolling back one distribution version moves the packaged code and plugin together.

A wheel is the archive installed into a Python environment. A source distribution, or sdist, carries source files that a build frontend can turn into a wheel.

Build planning

Build-backend adapters call build_plan() in the Python project directory. attach_wheel() does the same when plan is omitted. A caller with another configuration source can pass a validated BuildPlan directly.

The plan resolves [tool.agent-plugins].root and selects:

1. plugin.json at the plugin root.
2. Every file under skills/, when that directory exists.
3. mcp.json, when it exists at the plugin root.
4. Files and directory trees matched by include patterns.

Each FileMapping contains an absolute source Path and a plugin-root-relative PurePosixPath target. A POSIX path uses forward slashes so the artifact path stays stable across operating systems. Duplicate targets collapse into one mapping. Targets are sorted by their POSIX string.

Build planning validates the selection boundary. Document content is read through the inspection API after installation, or through another validator before release.

Regular wheels

A regular wheel contains the selected files in a sibling directory named from the wheel's distribution metadata:

site-packages/
├── my_project/
├── my_project-0.1.0.dist-info/
│   ├── agent_plugins.json
│   └── ...
└── my_project-0.1.0.agent-plugin/
    ├── plugin.json
    └── skills/

The adapter and attach_wheel() use the same wheel rewrite. It updates RECORD, the metadata table that lists installed paths, hashes, and byte sizes. Added files preserve executable mode bits.

The rewrite preserves the wheel's outer file mode, archive comment, and non-owned members. It removes invalidated RECORD.jws and RECORD.p7s signatures and reports their paths through WheelAttachment. A rerun replaces the owned marker and payload deterministically.

Direct attachment rewrites the input after a complete temporary artifact succeeds. Passing output_dir preserves the input and writes the same wheel filename into an existing destination directory. See Attach a prebuilt wheel for the complete operation.

The built distribution receives no runtime dependency on agent-plugins unless you declare one in [project].dependencies.

Source distributions

A source distribution, or sdist, carries the selected files under a reserved .agent-plugin/ staging directory.

When a build frontend reconstructs a wheel from the sdist, build_plan() uses the complete staged file selection. The rebuilt wheel therefore carries the same Agent Plugin payload captured in the source distribution, including files selected by authored include patterns.

Editable installs

An editable wheel stores an absolute path to the authored plugin root in agent_plugins.json. It records the selected relative filenames and does not copy the plugin directory into the wheel.

Edits to an already selected file appear on the next document read through a fresh handle. Adding or removing files changes the build plan, so reinstall the editable distribution to refresh the agent_plugins.json file inventory. See Editable installs for the complete lifecycle.

Installed discovery

locate(distribution_name) uses Python distribution metadata to find the agent_plugins.json marker. It contains:

• root: a relative installed directory for regular wheels, or an absolute authored root for editable wheels.
• files: the exact plugin-root-relative paths selected when the artifact was built.

Discovery resolves and validates every selected path before constructing a Plugin handle. It rejects missing files, directories listed as files, path traversal, backslashes, and paths that resolve outside the plugin root.

The resulting file inventory stays fixed for that handle. Parsed manifest, MCP, and skill contents have a second cache boundary described in Validation and caching.