agent-plugins 0.1.1__tar.gz → 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/.agent-plugin/plugin.json +1 -0
  2. agent_plugins-0.2.1/.agent-plugin/skills/agent-plugins/SKILL.md +250 -0
  3. agent_plugins-0.2.1/PKG-INFO +124 -0
  4. agent_plugins-0.2.1/README.md +103 -0
  5. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/pyproject.toml +3 -1
  6. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/pyproject.toml.orig +3 -1
  7. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/__init__.py +6 -1
  8. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_build/backend.py +3 -3
  9. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_build/plan.py +73 -10
  10. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_build/sdist.py +4 -2
  11. agent_plugins-0.2.1/src/agent_plugins/_build/wheel.py +239 -0
  12. agent_plugins-0.2.1/src/agent_plugins/_build/wheel_archive.py +292 -0
  13. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_cli.py +61 -2
  14. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_discovery.py +9 -1
  15. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_files.py +69 -13
  16. agent_plugins-0.2.1/src/agent_plugins/_mcp.py +198 -0
  17. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_plugin.py +63 -7
  18. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/__init__.py +2 -0
  19. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/json.py +14 -1
  20. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/lazy.py +2 -1
  21. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/manifest.py +10 -1
  22. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/mcp.py +48 -5
  23. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/models.py +15 -0
  24. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/skill.py +13 -4
  25. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/v1/mcp.py +14 -4
  26. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_skill.py +17 -4
  27. agent_plugins-0.1.1/.agent-plugin/skills/agent-plugins/SKILL.md +0 -195
  28. agent_plugins-0.1.1/PKG-INFO +0 -224
  29. agent_plugins-0.1.1/README.md +0 -205
  30. agent_plugins-0.1.1/src/agent_plugins/_build/wheel.py +0 -187
  31. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/.agent-plugin/skills/agent-plugins/agents/openai.yaml +0 -0
  32. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/LICENSE +0 -0
  33. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/__main__.py +0 -0
  34. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_build/__init__.py +0 -0
  35. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_errors.py +0 -0
  36. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_marker.py +0 -0
  37. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/errors.py +0 -0
  38. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/v1/__init__.py +0 -0
  39. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/v1/manifest.py +0 -0
  40. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_tree.py +0 -0
  41. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/build/__init__.py +0 -0
  42. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/build/hatchling.py +0 -0
  43. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/build/uv_build.py +0 -0
  44. {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/py.typed +0 -0
@@ -7,6 +7,7 @@
7
7
  "name": "Péter Ferenc Gyarmati",
8
8
  "email": "dev.petergy@gmail.com"
9
9
  },
10
+ "homepage": "https://peter-gy.github.io/agent-plugins/",
10
11
  "repository": "https://github.com/peter-gy/agent-plugins",
11
12
  "keywords": ["python", "agent-plugins", "agent-skills"]
12
13
  }
@@ -0,0 +1,250 @@
1
+ ---
2
+ name: agent-plugins
3
+ description: Ship and inspect Agent Skills, MCP server configuration, and client extension files with a Python distribution. Use when adding an Agent Plugin to a Python project, attaching a prebuilt wheel, loading the exact project or installed selection, selecting a named skill, reading checked skill resources, resolving a stdio MCP launch, or verifying package artifacts.
4
+ ---
5
+
6
+ # Agent Plugins
7
+
8
+ Use `agent-plugins` when a Python distribution should carry the instructions and MCP
9
+ configuration that match its installed code version.
10
+
11
+ An [Agent Plugin](https://agent-plugins.org/) is an open, vendor-neutral
12
+ portable directory format for reusable agent components. Its fixed locations
13
+ let compatible clients find [Agent Skills](https://agentskills.io/specification)
14
+ and [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification)
15
+ server configuration in the same package. Distribution, permissions, and user
16
+ experience remain with each client.
17
+
18
+ ## Build the plugin directory
19
+
20
+ Keep one Agent Plugin directory in the codebase:
21
+
22
+ ```text
23
+ my-plugin/
24
+ ├── plugin.json
25
+ ├── skills/
26
+ │ └── use-my-package/
27
+ │ ├── SKILL.md
28
+ │ ├── scripts/
29
+ │ └── references/
30
+ ├── mcp.json
31
+ └── com.example.client/
32
+ └── hooks/
33
+ ```
34
+
35
+ - `plugin.json` identifies the plugin and its Agent Plugins schema.
36
+ - `skills/` contains Agent Skills and their nested files.
37
+ - `mcp.json` describes stdio, Streamable HTTP, or legacy HTTP+SSE servers.
38
+ - Reverse-domain directories contain client extension files.
39
+
40
+ Create a minimal `plugin.json` at the plugin root:
41
+
42
+ ```json
43
+ {
44
+ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
45
+ "name": "my-project"
46
+ }
47
+ ```
48
+
49
+ Find the Python project's `pyproject.toml` and set
50
+ `[tool.agent-plugins].root` to the authored plugin root. Prefer a path relative
51
+ to `pyproject.toml`. For uv_build:
52
+
53
+ ```toml
54
+ [build-system]
55
+ requires = ["agent-plugins", "uv_build"]
56
+ build-backend = "agent_plugins.build.uv_build"
57
+
58
+ [tool.agent-plugins]
59
+ root = "../.."
60
+ ```
61
+
62
+ For Hatchling:
63
+
64
+ ```toml
65
+ [build-system]
66
+ requires = ["agent-plugins", "hatchling"]
67
+ build-backend = "agent_plugins.build.hatchling"
68
+
69
+ [tool.agent-plugins]
70
+ root = "../.."
71
+ ```
72
+
73
+ The build selects `plugin.json`, the complete `skills/` tree, and `mcp.json`
74
+ when present. Select other root-relative files explicitly:
75
+
76
+ ```toml
77
+ [tool.agent-plugins]
78
+ root = "../.."
79
+ include = ["bin/**", "com.example.client/**"]
80
+ ```
81
+
82
+ Every include pattern must stay within the plugin root and match at least one
83
+ filesystem entry. A matched directory contributes its regular files.
84
+
85
+ Use `attach_wheel()` when another build system already produced the wheel. It rewrites the input after the complete attached artifact succeeds. Pass `output_dir` to preserve the source.
86
+
87
+ ```python
88
+ import agent_plugins as ap
89
+
90
+ result = ap.attach_wheel(
91
+ "dist/my_package-1.0.0-py3-none-any.whl",
92
+ project="packages/python",
93
+ )
94
+ print(result.output)
95
+ ```
96
+
97
+ The CLI exposes the same operation:
98
+
99
+ ```console
100
+ agent-plugins attach-wheel dist/my_package-1.0.0-py3-none-any.whl \
101
+ --project packages/python
102
+ ```
103
+
104
+ Reuse a previously computed plan by passing it directly:
105
+
106
+ ```python
107
+ from pathlib import Path
108
+
109
+ plan = ap.build_plan("packages/python")
110
+ Path("dist/attached").mkdir(parents=True, exist_ok=True)
111
+ result = ap.attach_wheel(
112
+ "dist/my_package-1.0.0-py3-none-any.whl",
113
+ plan=plan,
114
+ output_dir="dist/attached",
115
+ )
116
+ ```
117
+
118
+ The output directory receives the same filename. Inspect `result.replaced_existing_plugin` and `result.removed_signatures`. The CLI writes removed-signature warnings to stderr.
119
+
120
+ `agent_plugins.build.BuildBackend` provides the wheel, source distribution, and
121
+ editable hooks used by the bundled adapters. A custom delegate must also expose
122
+ the three corresponding `get_requires_for_build_*` hooks.
123
+
124
+ ## Choose build-time or runtime access
125
+
126
+ Keeping `agent-plugins` in `[build-system].requires` makes it available during
127
+ the build. Add the package to `[project].dependencies` when installed Python
128
+ code needs to locate or inspect Agent Plugins:
129
+
130
+ ```toml
131
+ [project]
132
+ dependencies = ["agent-plugins"]
133
+ ```
134
+
135
+ Load the exact project selection before building. After installing a build from that selection, locate it with the Python distribution name used by pip:
136
+
137
+ ```python
138
+ import agent_plugins as ap
139
+
140
+ source = ap.Plugin.from_project("packages/python")
141
+ plugin = ap.locate("my-package")
142
+ skill = source.skill("use-my-package")
143
+
144
+ print(source.path)
145
+ print(plugin.path)
146
+ print(plugin.manifest.path)
147
+ print(plugin.manifest.name)
148
+ print(skill.source)
149
+ print(skill.file("SKILL.md"))
150
+
151
+ if mcp := plugin.mcp:
152
+ for name, server in mcp.servers.items():
153
+ print(name, server)
154
+ ```
155
+
156
+ `Plugin.from_project()` uses the build plan, so its files match the source
157
+ paths selected for packaging. `plugin.path` is the absolute installed plugin
158
+ root. Each item in
159
+ `plugin.skills` is an `ap.Skill` rooted at one immediate directory under
160
+ `skills/`. Use `plugin.skill(name)` for exact structural lookup. Use
161
+ `Path(skill)` or `skill.path` for that directory. Use `skill.file()` for a
162
+ selected instruction, reference, script, or asset:
163
+
164
+ ```python
165
+ print(skill.file("SKILL.md"))
166
+ print(skill.file("references/api.md"))
167
+ print(skill.tree(max_depth=2))
168
+ ```
169
+
170
+ `skill.source` returns the complete `SKILL.md` text. Use `skill.frontmatter`
171
+ for the raw source text between the `---` delimiters and `skill.body` for the
172
+ Markdown after the frontmatter. The package checks UTF-8 text and delimiter
173
+ structure. It does not parse the frontmatter as YAML. The first access to any
174
+ source property reads and splits `SKILL.md`, then caches all three strings. Path
175
+ and tree access leave the document unread so an agent can choose which files
176
+ and content to load.
177
+
178
+ `plugin.manifest` is an `ap.Manifest`. `plugin.mcp` is an `ap.MCPConfig` when
179
+ `mcp.json` exists. Each object exposes `.path` immediately. Accessing a parsed
180
+ field such as `manifest.name` or `mcp.servers` reads, validates, and caches its
181
+ document. MCP access validates the manifest first.
182
+
183
+ MCP servers are frozen `ap.StdioServer`, `ap.StreamableHTTPServer`, or
184
+ `ap.SSEServer` values in a read-only mapping. `manifest.issues` records
185
+ non-fatal manifest violations. `mcp.issues` records invalid server entries
186
+ skipped during loading. Document-level failures raise `ap.ValidationError` on
187
+ parsed value access.
188
+
189
+ Resolve a validated stdio server after the client creates its plugin data directory:
190
+
191
+ ```python
192
+ from pathlib import Path
193
+ import os
194
+
195
+ data_dir = Path(".agent-data/my-package").resolve()
196
+ data_dir.mkdir(parents=True, exist_ok=True)
197
+
198
+ mcp = plugin.mcp
199
+ if mcp is not None:
200
+ launch = mcp.resolve_stdio(
201
+ "my-package",
202
+ data_dir=data_dir,
203
+ base_env={"PATH": os.environ.get("PATH", "")},
204
+ )
205
+ print(launch.command, launch.args, launch.cwd)
206
+ ```
207
+
208
+ The client owns data retention, process creation, permissions, logging, and the MCP lifecycle. `resolve_stdio()` returns immutable subprocess inputs and performs one-pass Agent Plugins placeholder expansion.
209
+
210
+ Display the plugin to inspect its selected directory tree:
211
+
212
+ ```python
213
+ print(plugin)
214
+ print(plugin.tree(max_depth=2))
215
+ print(plugin.tree(max_depth=None, max_files=None))
216
+ ```
217
+
218
+ `Path(plugin)`, `Path(skill)`, and `Path(plugin.manifest)` use the native path
219
+ protocol. When `plugin.mcp` is present, `Path(plugin.mcp)` does too.
220
+ `ap.installed()` returns each discovered plugin keyed by Python distribution
221
+ name. Discovery is fail-fast when a marked distribution has unusable metadata
222
+ or selected files.
223
+
224
+ ## Verify the package
225
+
226
+ Inspect the selected paths before building:
227
+
228
+ ```console
229
+ agent-plugins plan path/to/python-project
230
+ ```
231
+
232
+ Then verify the package through its installation boundaries:
233
+
234
+ 1. Build a wheel and source distribution through an adapter, or attach the Agent Plugin after an external wheel build.
235
+ 2. Build a wheel from the source distribution.
236
+ 3. Install the wheel in a clean environment.
237
+ 4. Install the Python project as editable.
238
+ 5. Compare `Plugin.from_project()` with `ap.locate()` by plugin-relative file inventory and public component values.
239
+ 6. Access `plugin.manifest.name` and `plugin.mcp.servers` when MCP exists to run
240
+ the supported Agent Plugins JSON validation.
241
+ 7. Confirm each `skill.path`, `skill.file("SKILL.md")`, and `skill.files` points to
242
+ the packaged skill tree.
243
+ 8. Access `skill.source`, `skill.frontmatter`, and `skill.body` to verify UTF-8 text and the
244
+ packaged `SKILL.md` delimiter structure.
245
+ 9. Run an Agent Skills validator to check frontmatter fields and other Agent
246
+ Skills rules.
247
+
248
+ Handle `ap.AgentPluginError` when a requested Python distribution or usable plugin
249
+ root is absent. Handle `ap.ValidationError` when an installed plugin document
250
+ or `SKILL.md` structure is invalid.
@@ -0,0 +1,124 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-plugins
3
+ Version: 0.2.1
4
+ Summary: Ship Agent Plugins with Python packages and inspect their installed files
5
+ Author: Péter Ferenc Gyarmati
6
+ Author-email: Péter Ferenc Gyarmati <dev.petergy@gmail.com>
7
+ License-Expression: Apache-2.0
8
+ License-File: LICENSE
9
+ Classifier: Programming Language :: Python :: 3.10
10
+ Classifier: Programming Language :: Python :: 3.11
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Classifier: Programming Language :: Python :: 3.14
14
+ Classifier: Typing :: Typed
15
+ Requires-Dist: tomli==2.3.1 ; python_full_version < '3.11'
16
+ Requires-Python: >=3.10, <3.15
17
+ Project-URL: Documentation, https://peter-gy.github.io/agent-plugins/
18
+ Project-URL: Issues, https://github.com/peter-gy/agent-plugins/issues
19
+ Project-URL: Source, https://github.com/peter-gy/agent-plugins
20
+ Description-Content-Type: text/markdown
21
+
22
+ <p align="center">
23
+ <picture>
24
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-dark.svg">
25
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-light.svg">
26
+ <img alt="agent-plugins" src="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-light.svg" width="430">
27
+ </picture>
28
+ </p>
29
+
30
+ <p align="center">
31
+ Ship Agent Plugins with Python packages.
32
+ </p>
33
+
34
+ <p align="center">
35
+ <a href="https://peter-gy.github.io/agent-plugins/"><strong>Documentation</strong></a> ·
36
+ <a href="https://pypi.org/project/agent-plugins/"><strong>PyPI</strong></a> ·
37
+ <a href="https://agent-plugins.org/"><strong>Agent Plugins format</strong></a>
38
+ </p>
39
+
40
+ <p align="center">
41
+ <a href="https://pypi.org/project/agent-plugins/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/agent-plugins"></a>
42
+ <a href="https://pypi.org/project/agent-plugins/"><img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/agent-plugins"></a>
43
+ <a href="https://github.com/peter-gy/agent-plugins/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/peter-gy/agent-plugins/actions/workflows/ci.yml/badge.svg"></a>
44
+ <a href="https://github.com/peter-gy/agent-plugins/blob/main/LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/pypi/l/agent-plugins"></a>
45
+ </p>
46
+
47
+ `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.
48
+
49
+ The [Agent Plugins format](https://agent-plugins.org/) defines the directory: a manifest, [Agent Skills](https://agentskills.io/specification) for instructions and resources, [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification) 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.
50
+
51
+ ## Package your plugin
52
+
53
+ Keep `plugin.json` and `skills/` beside your code. For a project using the [uv build backend](https://docs.astral.sh/uv/concepts/build-backend/), configure `pyproject.toml`:
54
+
55
+ ```toml
56
+ [build-system]
57
+ requires = ["agent-plugins", "uv_build"]
58
+ build-backend = "agent_plugins.build.uv_build"
59
+
60
+ [tool.agent-plugins]
61
+ root = "."
62
+ ```
63
+
64
+ Build with the [uv package manager](https://docs.astral.sh/uv/):
65
+
66
+ ```console
67
+ uv build
68
+ ```
69
+
70
+ The [quickstart](https://peter-gy.github.io/agent-plugins/guide/getting-started) creates a complete project, builds it, and locates the installed plugin. Use the [Hatchling adapter](https://peter-gy.github.io/agent-plugins/guide/build-backends#hatchling) for Hatchling projects, or [attach a prebuilt wheel](https://peter-gy.github.io/agent-plugins/guide/attach-wheel) when another tool owns the build:
71
+
72
+ ```console
73
+ agent-plugins attach-wheel dist/my_project-0.1.0-py3-none-any.whl --project .
74
+ ```
75
+
76
+ Attachment updates the wheel in place. Pass `--output-dir` to preserve the input.
77
+
78
+ ## Inspect an installed plugin
79
+
80
+ Install `agent-plugins` in the environment you want to inspect. The package includes its own Agent Skill:
81
+
82
+ ```console
83
+ pip install agent-plugins
84
+ ```
85
+
86
+ ```python
87
+ import agent_plugins as ap
88
+
89
+ plugin = ap.locate("agent-plugins")
90
+ skill = plugin.skill("agent-plugins")
91
+
92
+ print(skill.source)
93
+ print(skill.file("SKILL.md"))
94
+ ```
95
+
96
+ Pass your library's distribution name to `locate()` to inspect its plugin. Use [`Plugin.from_project()`](https://peter-gy.github.io/agent-plugins/guide/inspect-project) to inspect the selected source files before building.
97
+
98
+ ## Documentation
99
+
100
+ - [Get started](https://peter-gy.github.io/agent-plugins/guide/getting-started): package, install, and locate a plugin.
101
+ - [How packaging works](https://peter-gy.github.io/agent-plugins/guide/artifact-lifecycle): wheels, source distributions, and editable installs.
102
+ - [Integrate](https://peter-gy.github.io/agent-plugins/guide/inspect-installed): read skills, inspect files, and resolve MCP configuration.
103
+ - [Python API](https://peter-gy.github.io/agent-plugins/reference/python-api) · [CLI](https://peter-gy.github.io/agent-plugins/reference/cli) · [Configuration](https://peter-gy.github.io/agent-plugins/reference/pyproject)
104
+
105
+ <details>
106
+ <summary>Packaging lifecycle</summary>
107
+
108
+ <p align="center">
109
+ <picture>
110
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-dark.svg">
111
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-light.svg">
112
+ <img alt="Core model: an authored Python project builds into one wheel that installs the library beside its version-matched Agent Plugin, which locate() returns as a plugin handle" src="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-light.svg" width="300">
113
+ </picture>
114
+ </p>
115
+
116
+ </details>
117
+
118
+ ## Development
119
+
120
+ See [development_docs/](https://github.com/peter-gy/agent-plugins/tree/main/development_docs) for setup, architecture, checks, and releases. Serve the documentation locally with `pnpm --dir docs dev`.
121
+
122
+ ## License
123
+
124
+ [Apache-2.0](https://github.com/peter-gy/agent-plugins/blob/main/LICENSE).
@@ -0,0 +1,103 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-dark.svg">
4
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-light.svg">
5
+ <img alt="agent-plugins" src="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-light.svg" width="430">
6
+ </picture>
7
+ </p>
8
+
9
+ <p align="center">
10
+ Ship Agent Plugins with Python packages.
11
+ </p>
12
+
13
+ <p align="center">
14
+ <a href="https://peter-gy.github.io/agent-plugins/"><strong>Documentation</strong></a> ·
15
+ <a href="https://pypi.org/project/agent-plugins/"><strong>PyPI</strong></a> ·
16
+ <a href="https://agent-plugins.org/"><strong>Agent Plugins format</strong></a>
17
+ </p>
18
+
19
+ <p align="center">
20
+ <a href="https://pypi.org/project/agent-plugins/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/agent-plugins"></a>
21
+ <a href="https://pypi.org/project/agent-plugins/"><img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/agent-plugins"></a>
22
+ <a href="https://github.com/peter-gy/agent-plugins/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/peter-gy/agent-plugins/actions/workflows/ci.yml/badge.svg"></a>
23
+ <a href="https://github.com/peter-gy/agent-plugins/blob/main/LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/pypi/l/agent-plugins"></a>
24
+ </p>
25
+
26
+ `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.
27
+
28
+ The [Agent Plugins format](https://agent-plugins.org/) defines the directory: a manifest, [Agent Skills](https://agentskills.io/specification) for instructions and resources, [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification) 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.
29
+
30
+ ## Package your plugin
31
+
32
+ Keep `plugin.json` and `skills/` beside your code. For a project using the [uv build backend](https://docs.astral.sh/uv/concepts/build-backend/), configure `pyproject.toml`:
33
+
34
+ ```toml
35
+ [build-system]
36
+ requires = ["agent-plugins", "uv_build"]
37
+ build-backend = "agent_plugins.build.uv_build"
38
+
39
+ [tool.agent-plugins]
40
+ root = "."
41
+ ```
42
+
43
+ Build with the [uv package manager](https://docs.astral.sh/uv/):
44
+
45
+ ```console
46
+ uv build
47
+ ```
48
+
49
+ The [quickstart](https://peter-gy.github.io/agent-plugins/guide/getting-started) creates a complete project, builds it, and locates the installed plugin. Use the [Hatchling adapter](https://peter-gy.github.io/agent-plugins/guide/build-backends#hatchling) for Hatchling projects, or [attach a prebuilt wheel](https://peter-gy.github.io/agent-plugins/guide/attach-wheel) when another tool owns the build:
50
+
51
+ ```console
52
+ agent-plugins attach-wheel dist/my_project-0.1.0-py3-none-any.whl --project .
53
+ ```
54
+
55
+ Attachment updates the wheel in place. Pass `--output-dir` to preserve the input.
56
+
57
+ ## Inspect an installed plugin
58
+
59
+ Install `agent-plugins` in the environment you want to inspect. The package includes its own Agent Skill:
60
+
61
+ ```console
62
+ pip install agent-plugins
63
+ ```
64
+
65
+ ```python
66
+ import agent_plugins as ap
67
+
68
+ plugin = ap.locate("agent-plugins")
69
+ skill = plugin.skill("agent-plugins")
70
+
71
+ print(skill.source)
72
+ print(skill.file("SKILL.md"))
73
+ ```
74
+
75
+ Pass your library's distribution name to `locate()` to inspect its plugin. Use [`Plugin.from_project()`](https://peter-gy.github.io/agent-plugins/guide/inspect-project) to inspect the selected source files before building.
76
+
77
+ ## Documentation
78
+
79
+ - [Get started](https://peter-gy.github.io/agent-plugins/guide/getting-started): package, install, and locate a plugin.
80
+ - [How packaging works](https://peter-gy.github.io/agent-plugins/guide/artifact-lifecycle): wheels, source distributions, and editable installs.
81
+ - [Integrate](https://peter-gy.github.io/agent-plugins/guide/inspect-installed): read skills, inspect files, and resolve MCP configuration.
82
+ - [Python API](https://peter-gy.github.io/agent-plugins/reference/python-api) · [CLI](https://peter-gy.github.io/agent-plugins/reference/cli) · [Configuration](https://peter-gy.github.io/agent-plugins/reference/pyproject)
83
+
84
+ <details>
85
+ <summary>Packaging lifecycle</summary>
86
+
87
+ <p align="center">
88
+ <picture>
89
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-dark.svg">
90
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-light.svg">
91
+ <img alt="Core model: an authored Python project builds into one wheel that installs the library beside its version-matched Agent Plugin, which locate() returns as a plugin handle" src="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-light.svg" width="300">
92
+ </picture>
93
+ </p>
94
+
95
+ </details>
96
+
97
+ ## Development
98
+
99
+ See [development_docs/](https://github.com/peter-gy/agent-plugins/tree/main/development_docs) for setup, architecture, checks, and releases. Serve the documentation locally with `pnpm --dir docs dev`.
100
+
101
+ ## License
102
+
103
+ [Apache-2.0](https://github.com/peter-gy/agent-plugins/blob/main/LICENSE).
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "agent-plugins"
3
- version = "0.1.1"
3
+ version = "0.2.1"
4
4
  description = "Ship Agent Plugins with Python packages and inspect their installed files"
5
5
  readme = "README.md"
6
6
  license = "Apache-2.0"
@@ -21,6 +21,8 @@ name = "Péter Ferenc Gyarmati"
21
21
  email = "dev.petergy@gmail.com"
22
22
 
23
23
  [project.urls]
24
+ Documentation = "https://peter-gy.github.io/agent-plugins/"
25
+ Issues = "https://github.com/peter-gy/agent-plugins/issues"
24
26
  Source = "https://github.com/peter-gy/agent-plugins"
25
27
 
26
28
  [project.scripts]
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "agent-plugins"
3
- version = "0.1.1"
3
+ version = "0.2.1"
4
4
  description = "Ship Agent Plugins with Python packages and inspect their installed files"
5
5
  readme = "README.md"
6
6
  license = "Apache-2.0"
@@ -22,6 +22,8 @@ classifiers = [
22
22
  ]
23
23
 
24
24
  [project.urls]
25
+ Documentation = "https://peter-gy.github.io/agent-plugins/"
26
+ Issues = "https://github.com/peter-gy/agent-plugins/issues"
25
27
  Source = "https://github.com/peter-gy/agent-plugins"
26
28
 
27
29
  [project.scripts]
@@ -1,6 +1,7 @@
1
- """Locate and inspect Agent Plugins installed by Python distributions."""
1
+ """Package and inspect Agent Plugins through Python distributions."""
2
2
 
3
3
  from ._build.plan import BuildPlan, FileMapping, build_plan
4
+ from ._build.wheel import WheelAttachment, attach_wheel
4
5
  from ._discovery import installed, locate
5
6
  from ._errors import AgentPluginError
6
7
  from ._plugin import Plugin
@@ -9,6 +10,7 @@ from ._schema import (
9
10
  Manifest,
10
11
  MCPConfig,
11
12
  MCPServer,
13
+ ResolvedStdioServer,
12
14
  SSEServer,
13
15
  StdioServer,
14
16
  StreamableHTTPServer,
@@ -26,12 +28,15 @@ __all__ = [
26
28
  "MCPServer",
27
29
  "Manifest",
28
30
  "Plugin",
31
+ "ResolvedStdioServer",
29
32
  "SSEServer",
30
33
  "Skill",
31
34
  "StdioServer",
32
35
  "StreamableHTTPServer",
33
36
  "ValidationError",
34
37
  "ValidationIssue",
38
+ "WheelAttachment",
39
+ "attach_wheel",
35
40
  "build_plan",
36
41
  "installed",
37
42
  "locate",
@@ -10,7 +10,7 @@ from typing import Protocol, cast
10
10
 
11
11
  from .plan import build_plan
12
12
  from .sdist import write_sdist_plugin
13
- from .wheel import write_wheel_plugin
13
+ from .wheel import _attach_editable_wheel, attach_wheel
14
14
 
15
15
  ConfigSettings = dict[str, object] | None
16
16
 
@@ -66,7 +66,7 @@ class BuildBackend:
66
66
  filename = self._delegate.build_wheel(
67
67
  wheel_directory, config_settings, metadata_directory
68
68
  )
69
- write_wheel_plugin(Path(wheel_directory) / filename, plan)
69
+ attach_wheel(Path(wheel_directory) / filename, plan=plan)
70
70
  return filename
71
71
 
72
72
  def build_sdist(
@@ -91,7 +91,7 @@ class BuildBackend:
91
91
  filename = self._delegate.build_editable(
92
92
  wheel_directory, config_settings, metadata_directory
93
93
  )
94
- write_wheel_plugin(Path(wheel_directory) / filename, plan, editable=True)
94
+ _attach_editable_wheel(Path(wheel_directory) / filename, plan)
95
95
  return filename
96
96
 
97
97
  def get_requires_for_build_wheel(