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

{agent_plugins-0.1.1 → agent_plugins-0.2.0}/.agent-plugin/plugin.json

@@ -7,6 +7,7 @@
     "name": "Péter Ferenc Gyarmati",
     "email": "dev.petergy@gmail.com"
   },
+  "homepage": "https://peter-gy.github.io/agent-plugins/",
   "repository": "https://github.com/peter-gy/agent-plugins",
   "keywords": ["python", "agent-plugins", "agent-skills"]
 }

agent_plugins-0.2.0/.agent-plugin/skills/agent-plugins/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: agent-plugins
+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.
+---
+
+# Agent Plugins
+
+Use `agent-plugins` when a Python distribution should carry the instructions and MCP
+configuration that match its installed code version.
+
+An [Agent Plugin](https://agent-plugins.org/) is an open, vendor-neutral
+portable directory format for reusable agent components. Its fixed locations
+let compatible clients find [Agent Skills](https://agentskills.io/specification)
+and [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification)
+server configuration in the same package. Distribution, permissions, and user
+experience remain with each client.
+
+## Build the plugin directory
+
+Keep one Agent Plugin directory in the codebase:
+
+```text
+my-plugin/
+├── plugin.json
+├── skills/
+│   └── use-my-package/
+│       ├── SKILL.md
+│       ├── scripts/
+│       └── references/
+├── mcp.json
+└── com.example.client/
+    └── hooks/
+```
+
+- `plugin.json` identifies the plugin and its Agent Plugins schema.
+- `skills/` contains Agent Skills and their nested files.
+- `mcp.json` describes stdio, Streamable HTTP, or legacy HTTP+SSE servers.
+- Reverse-domain directories contain client extension files.
+
+Create a minimal `plugin.json` at the plugin root:
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "my-project"
+}
+```
+
+Find the Python project's `pyproject.toml` and set
+`[tool.agent-plugins].root` to the authored plugin root. Prefer a path relative
+to `pyproject.toml`. For uv_build:
+
+```toml
+[build-system]
+requires = ["agent-plugins", "uv_build"]
+build-backend = "agent_plugins.build.uv_build"
+
+[tool.agent-plugins]
+root = "../.."
+```
+
+For Hatchling:
+
+```toml
+[build-system]
+requires = ["agent-plugins", "hatchling"]
+build-backend = "agent_plugins.build.hatchling"
+
+[tool.agent-plugins]
+root = "../.."
+```
+
+The build selects `plugin.json`, the complete `skills/` tree, and `mcp.json`
+when present. Select other root-relative files explicitly:
+
+```toml
+[tool.agent-plugins]
+root = "../.."
+include = ["bin/**", "com.example.client/**"]
+```
+
+Every include pattern must stay within the plugin root and match at least one
+filesystem entry. A matched directory contributes its regular files.
+
+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.
+
+```python
+import agent_plugins as ap
+
+result = ap.attach_wheel(
+    "dist/my_package-1.0.0-py3-none-any.whl",
+    project="packages/python",
+)
+print(result.output)
+```
+
+The CLI exposes the same operation:
+
+```console
+agent-plugins attach-wheel dist/my_package-1.0.0-py3-none-any.whl \
+  --project packages/python
+```
+
+Reuse a previously computed plan by passing it directly:
+
+```python
+from pathlib import Path
+
+plan = ap.build_plan("packages/python")
+Path("dist/attached").mkdir(parents=True, exist_ok=True)
+result = ap.attach_wheel(
+    "dist/my_package-1.0.0-py3-none-any.whl",
+    plan=plan,
+    output_dir="dist/attached",
+)
+```
+
+The output directory receives the same filename. Inspect `result.replaced_existing_plugin` and `result.removed_signatures`. The CLI writes removed-signature warnings to stderr.
+
+`agent_plugins.build.BuildBackend` provides the wheel, source distribution, and
+editable hooks used by the bundled adapters. A custom delegate must also expose
+the three corresponding `get_requires_for_build_*` hooks.
+
+## Choose build-time or runtime access
+
+Keeping `agent-plugins` in `[build-system].requires` makes it available during
+the build. Add the package to `[project].dependencies` when installed Python
+code needs to locate or inspect Agent Plugins:
+
+```toml
+[project]
+dependencies = ["agent-plugins"]
+```
+
+Load the exact project selection before building. After installing a build from that selection, locate it with the Python distribution name used by pip:
+
+```python
+import agent_plugins as ap
+
+source = ap.Plugin.from_project("packages/python")
+plugin = ap.locate("my-package")
+skill = source.skill("use-my-package")
+
+print(source.path)
+print(plugin.path)
+print(plugin.manifest.path)
+print(plugin.manifest.name)
+print(skill.source)
+print(skill.file("SKILL.md"))
+
+if mcp := plugin.mcp:
+    for name, server in mcp.servers.items():
+        print(name, server)
+```
+
+`Plugin.from_project()` uses the build plan, so its files match the source
+paths selected for packaging. `plugin.path` is the absolute installed plugin
+root. Each item in
+`plugin.skills` is an `ap.Skill` rooted at one immediate directory under
+`skills/`. Use `plugin.skill(name)` for exact structural lookup. Use
+`Path(skill)` or `skill.path` for that directory. Use `skill.file()` for a
+selected instruction, reference, script, or asset:
+
+```python
+print(skill.file("SKILL.md"))
+print(skill.file("references/api.md"))
+print(skill.tree(max_depth=2))
+```
+
+`skill.source` returns the complete `SKILL.md` text. Use `skill.frontmatter`
+for the raw source text between the `---` delimiters and `skill.body` for the
+Markdown after the frontmatter. The package checks UTF-8 text and delimiter
+structure. It does not parse the frontmatter as YAML. The first access to any
+source property reads and splits `SKILL.md`, then caches all three strings. Path
+and tree access leave the document unread so an agent can choose which files
+and content to load.
+
+`plugin.manifest` is an `ap.Manifest`. `plugin.mcp` is an `ap.MCPConfig` when
+`mcp.json` exists. Each object exposes `.path` immediately. Accessing a parsed
+field such as `manifest.name` or `mcp.servers` reads, validates, and caches its
+document. MCP access validates the manifest first.
+
+MCP servers are frozen `ap.StdioServer`, `ap.StreamableHTTPServer`, or
+`ap.SSEServer` values in a read-only mapping. `manifest.issues` records
+non-fatal manifest violations. `mcp.issues` records invalid server entries
+skipped during loading. Document-level failures raise `ap.ValidationError` on
+parsed value access.
+
+Resolve a validated stdio server after the client creates its plugin data directory:
+
+```python
+from pathlib import Path
+import os
+
+data_dir = Path(".agent-data/my-package").resolve()
+data_dir.mkdir(parents=True, exist_ok=True)
+
+mcp = plugin.mcp
+if mcp is not None:
+    launch = mcp.resolve_stdio(
+        "my-package",
+        data_dir=data_dir,
+        base_env={"PATH": os.environ.get("PATH", "")},
+    )
+    print(launch.command, launch.args, launch.cwd)
+```
+
+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.
+
+Display the plugin to inspect its selected directory tree:
+
+```python
+print(plugin)
+print(plugin.tree(max_depth=2))
+print(plugin.tree(max_depth=None, max_files=None))
+```
+
+`Path(plugin)`, `Path(skill)`, and `Path(plugin.manifest)` use the native path
+protocol. When `plugin.mcp` is present, `Path(plugin.mcp)` does too.
+`ap.installed()` returns each discovered plugin keyed by Python distribution
+name. Discovery is fail-fast when a marked distribution has unusable metadata
+or selected files.
+
+## Verify the package
+
+Inspect the selected paths before building:
+
+```console
+agent-plugins plan path/to/python-project
+```
+
+Then verify the package through its installation boundaries:
+
+1. Build a wheel and source distribution through an adapter, or attach the Agent Plugin after an external wheel build.
+2. Build a wheel from the source distribution.
+3. Install the wheel in a clean environment.
+4. Install the Python project as editable.
+5. Compare `Plugin.from_project()` with `ap.locate()` by plugin-relative file inventory and public component values.
+6. Access `plugin.manifest.name` and `plugin.mcp.servers` when MCP exists to run
+   the supported Agent Plugins JSON validation.
+7. Confirm each `skill.path`, `skill.file("SKILL.md")`, and `skill.files` points to
+   the packaged skill tree.
+8. Access `skill.source`, `skill.frontmatter`, and `skill.body` to verify UTF-8 text and the
+   packaged `SKILL.md` delimiter structure.
+9. Run an Agent Skills validator to check frontmatter fields and other Agent
+   Skills rules.
+
+Handle `ap.AgentPluginError` when a requested Python distribution or usable plugin
+root is absent. Handle `ap.ValidationError` when an installed plugin document
+or `SKILL.md` structure is invalid.

agent_plugins-0.2.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: agent-plugins
+Version: 0.2.0
+Summary: Ship Agent Plugins with Python packages and inspect their installed files
+Author: Péter Ferenc Gyarmati
+Author-email: Péter Ferenc Gyarmati <dev.petergy@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: tomli==2.3.1 ; python_full_version < '3.11'
+Requires-Python: >=3.10, <3.15
+Project-URL: Documentation, https://peter-gy.github.io/agent-plugins/
+Project-URL: Issues, https://github.com/peter-gy/agent-plugins/issues
+Project-URL: Source, https://github.com/peter-gy/agent-plugins
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <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">
+    <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">
+    <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">
+  </picture>
+</p>
+
+<p align="center">
+  Ship Agent Plugins with Python packages.
+</p>
+
+<p align="center">
+  <a href="https://peter-gy.github.io/agent-plugins/"><strong>Documentation</strong></a> ·
+  <a href="https://pypi.org/project/agent-plugins/"><strong>PyPI</strong></a> ·
+  <a href="https://agent-plugins.org/"><strong>Agent Plugins format</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/agent-plugins/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/agent-plugins"></a>
+  <a href="https://pypi.org/project/agent-plugins/"><img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/agent-plugins"></a>
+  <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>
+  <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>
+</p>
+
+[Agent Plugins](https://agent-plugins.org/) gives reusable [Agent Skills](https://agentskills.io/specification) and [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification) 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](https://peter-gy.github.io/agent-plugins/integrations/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](https://packaging.python.org/en/latest/specifications/binary-distribution-format/) and [source distributions](https://packaging.python.org/en/latest/specifications/source-distribution-format/) 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.
+
+```console
+agent-plugins attach-wheel dist/example-1.0.0-py3-none-any.whl --project .
+```
+
+```python
+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](https://peter-gy.github.io/agent-plugins/guide/attach-wheel) for output copies, result fields, reruns, and signature handling.
+
+## Quickstart
+
+Keep the plugin directory beside its Python package:
+
+```text
+my-project/
+├── plugin.json
+├── skills/
+│   └── use-my-project/
+│       └── SKILL.md
+└── packages/
+    └── python/
+        ├── pyproject.toml
+        └── src/
+            └── my_project/
+                └── __init__.py
+```
+
+Create `plugin.json`:
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "my-project"
+}
+```
+
+Create `skills/use-my-project/SKILL.md`:
+
+```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](https://docs.astral.sh/uv/concepts/build-backend/) in `packages/python/pyproject.toml`:
+
+```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](https://docs.astral.sh/uv/) installed, preview the selected files, build the package, install the wheel in a temporary environment, and locate its Agent Plugin:
+
+```console
+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
+```
+
+```text
+/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](https://peter-gy.github.io/agent-plugins/guide/getting-started) 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:
+
+```toml
+[project]
+dependencies = ["agent-plugins"]
+```
+
+```python
+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](https://peter-gy.github.io/agent-plugins/guide/inspect-installed).
+
+## Core model
+
+<p align="center">
+  <picture>
+    <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">
+    <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">
+    <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">
+  </picture>
+</p>
+
+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](https://tanstack.com/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/`](https://github.com/peter-gy/agent-plugins/tree/main/development_docs) covers contributor setup, architecture, testing, packaging, documentation, and releases. Serve the docs through [Portless](https://portless.sh/):
+
+```console
+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](https://github.com/peter-gy/agent-plugins/blob/main/LICENSE).

agent_plugins-0.2.0/README.md

@@ -0,0 +1,185 @@
+<p align="center">
+  <picture>
+    <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">
+    <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">
+    <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">
+  </picture>
+</p>
+
+<p align="center">
+  Ship Agent Plugins with Python packages.
+</p>
+
+<p align="center">
+  <a href="https://peter-gy.github.io/agent-plugins/"><strong>Documentation</strong></a> ·
+  <a href="https://pypi.org/project/agent-plugins/"><strong>PyPI</strong></a> ·
+  <a href="https://agent-plugins.org/"><strong>Agent Plugins format</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/agent-plugins/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/agent-plugins"></a>
+  <a href="https://pypi.org/project/agent-plugins/"><img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/agent-plugins"></a>
+  <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>
+  <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>
+</p>
+
+[Agent Plugins](https://agent-plugins.org/) gives reusable [Agent Skills](https://agentskills.io/specification) and [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification) 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](https://peter-gy.github.io/agent-plugins/integrations/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](https://packaging.python.org/en/latest/specifications/binary-distribution-format/) and [source distributions](https://packaging.python.org/en/latest/specifications/source-distribution-format/) 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.
+
+```console
+agent-plugins attach-wheel dist/example-1.0.0-py3-none-any.whl --project .
+```
+
+```python
+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](https://peter-gy.github.io/agent-plugins/guide/attach-wheel) for output copies, result fields, reruns, and signature handling.
+
+## Quickstart
+
+Keep the plugin directory beside its Python package:
+
+```text
+my-project/
+├── plugin.json
+├── skills/
+│   └── use-my-project/
+│       └── SKILL.md
+└── packages/
+    └── python/
+        ├── pyproject.toml
+        └── src/
+            └── my_project/
+                └── __init__.py
+```
+
+Create `plugin.json`:
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "my-project"
+}
+```
+
+Create `skills/use-my-project/SKILL.md`:
+
+```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](https://docs.astral.sh/uv/concepts/build-backend/) in `packages/python/pyproject.toml`:
+
+```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](https://docs.astral.sh/uv/) installed, preview the selected files, build the package, install the wheel in a temporary environment, and locate its Agent Plugin:
+
+```console
+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
+```
+
+```text
+/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](https://peter-gy.github.io/agent-plugins/guide/getting-started) 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:
+
+```toml
+[project]
+dependencies = ["agent-plugins"]
+```
+
+```python
+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](https://peter-gy.github.io/agent-plugins/guide/inspect-installed).
+
+## Core model
+
+<p align="center">
+  <picture>
+    <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">
+    <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">
+    <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">
+  </picture>
+</p>
+
+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](https://tanstack.com/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/`](https://github.com/peter-gy/agent-plugins/tree/main/development_docs) covers contributor setup, architecture, testing, packaging, documentation, and releases. Serve the docs through [Portless](https://portless.sh/):
+
+```console
+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](https://github.com/peter-gy/agent-plugins/blob/main/LICENSE).

{agent_plugins-0.1.1 → agent_plugins-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-plugins"
-version = "0.1.1"
+version = "0.2.0"
 description = "Ship Agent Plugins with Python packages and inspect their installed files"
 readme = "README.md"
 license = "Apache-2.0"
@@ -21,6 +21,8 @@ name = "Péter Ferenc Gyarmati"
 email = "dev.petergy@gmail.com"
 
 [project.urls]
+Documentation = "https://peter-gy.github.io/agent-plugins/"
+Issues = "https://github.com/peter-gy/agent-plugins/issues"
 Source = "https://github.com/peter-gy/agent-plugins"
 
 [project.scripts]