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

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

@@ -0,0 +1,103 @@
+---
+name: agent-plugins
+description: Read and inspect the version-matched Agent Plugin carried by an installed Python distribution. Use when a package README points to agent-plugins, when loading packaged Agent Skills and resources, listing or locating installed plugins, inspecting manifest or MCP summaries, or troubleshooting discovery. For adding Agent Plugin packaging to a repository, use the package-agent-plugin skill.
+---
+
+# Read installed Agent Plugins
+
+Use `agent-plugins` to load the instructions and resources shipped with the
+same version of a Python package that the agent will use.
+
+## Start from a package README
+
+Run the package and `agent-plugins` in one temporary environment:
+
+```console
+uvx --with my-package agent-plugins read my-package
+```
+
+The requirement after `--with` tells uv what to install. The final argument is
+the installed Python distribution to inspect. Use a version constraint when
+the task requires an exact release:
+
+```console
+uvx --with 'my-package==1.2.3' agent-plugins read my-package
+```
+
+Follow each applicable skill in the output. Resolve its relative links from the
+instruction file's directory. Use `--skill NAME` when one plugin carries
+several skills and the task needs a single workflow.
+
+`read` reports MCP metadata for discovery. It does not start servers or print
+configured commands, arguments, environment values, URLs, or headers. The
+agent client owns component activation, permissions, processes, and data.
+
+## Choose the CLI operation
+
+| Task | Command |
+| --- | --- |
+| Read one installed plugin and all primary instructions | `agent-plugins read DISTRIBUTION` |
+| Read one named skill with the plugin context | `agent-plugins read DISTRIBUTION --skill NAME` |
+| List every discoverable plugin and skill path | `agent-plugins list` |
+| List discoverable plugins as JSON | `agent-plugins list --json` |
+| Print one installed plugin root | `agent-plugins locate DISTRIBUTION` |
+| Preview files selected from a source project | `agent-plugins plan [PROJECT]` |
+| Attach a configured plugin to a prebuilt wheel | `agent-plugins attach-wheel WHEEL` |
+
+`plan` and `attach-wheel` are repository packaging operations. Load the
+`package-agent-plugin` skill before changing a project or wheel.
+
+Running `uvx agent-plugins` with no arguments reads the Agent Plugin carried by
+`agent-plugins` itself. It is the shortcut for:
+
+```console
+uvx agent-plugins read agent-plugins
+```
+
+Use `agent-plugins --help` or `agent-plugins COMMAND --help` for command syntax.
+Successful commands write data to stdout. Expected discovery, validation,
+configuration, and filesystem failures return status `1` with an
+`agent-plugins: error:` diagnostic on stderr. Argument errors return status
+`2`.
+
+## Read the current Python environment
+
+When the target package is already installed in the active environment, run:
+
+```console
+agent-plugins read my-package
+```
+
+Use the Python API when the task needs one skill or a linked resource:
+
+```python
+import agent_plugins as ap
+
+plugin = ap.locate("my-package")
+skill = plugin.skill("use-my-package")
+
+print(skill.source)
+reference = skill.file("references/api.md")
+print(reference.read_text(encoding="utf-8"))
+```
+
+`plugin.skills` contains every immediate `skills/<name>/SKILL.md` selected by
+the installed package. `skill.file()` accepts an exact selected path below that
+skill and rechecks containment. `plugin.tree()` and `skill.tree()` provide a
+bounded inventory before reading more files.
+
+Use `plugin.manifest` for validated plugin metadata. `plugin.mcp` is an
+`MCPConfig` when the package selected `mcp.json`. Accessing parsed manifest or
+MCP fields validates and caches the document. Handle `AgentPluginError` for
+missing or unusable installed plugins and `ValidationError` for invalid plugin,
+MCP, or skill documents.
+
+## Keep the environment explicit
+
+`uvx` creates a temporary environment for the command. Install the package in
+the notebook, service, or project environment where its Python API will run.
+The instructions printed by `read` describe the exact distribution version
+resolved for that command.
+
+Python distribution names and manifest plugin names are independent. Pass the
+name used by pip or uv to `read`, `locate`, and `ap.locate()`.

agent_plugins-0.2.3/.agent-plugin/skills/agent-plugins/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Read Agent Plugins"
+  short_description: "Load packaged instructions from Python distributions"
+  default_prompt: "Use $agent-plugins to read the version-matched instructions packaged with this Python distribution."

agent_plugins-0.2.3/.agent-plugin/skills/package-agent-plugin/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: package-agent-plugin
+description: Add Agent Plugin packaging to a Python project. Use when creating plugin.json and skills, configuring uv_build or Hatchling, attaching a plugin to a prebuilt wheel, exposing runtime plugin access, or verifying wheel, source distribution, and editable artifacts. For consuming instructions from an installed package, use the agent-plugins skill.
+---
+
+# Package an Agent Plugin
+
+Package instructions beside the Python code they describe so the library and
+its Agent Plugin share one release.
+
+## Build the smallest complete integration
+
+For a single-package project, keep the plugin at the project root:
+
+```text
+my-package/
+|-- plugin.json
+|-- pyproject.toml
+|-- skills/
+|   `-- use-my-package/
+|       `-- SKILL.md
+`-- src/
+    `-- my_package/
+```
+
+Create `plugin.json`:
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "my-package",
+  "description": "Use My Package from Python."
+}
+```
+
+Create `skills/use-my-package/SKILL.md` with a discriminating description and
+the shortest complete workflow an agent needs:
+
+```md
+---
+name: use-my-package
+description: Use My Package to read and transform project records from Python.
+---
+
+# Use My Package
+
+Import `my_package`, open the project input, and call `transform()`.
+```
+
+Configure an existing uv_build project in `pyproject.toml`:
+
+```toml
+[build-system]
+requires = ["agent-plugins", "uv_build"]
+build-backend = "agent_plugins.build.uv_build"
+
+[tool.agent-plugins]
+root = "."
+```
+
+Preview the exact selection, then build:
+
+```console
+uv run --with agent-plugins agent-plugins plan .
+uv build
+```
+
+The plan must contain `plugin.json`, every intended file under `skills/`, and
+`mcp.json` when configured. Add root-relative client extension files or other
+plugin resources through `[tool.agent-plugins].include`.
+
+## Verify the installed handoff
+
+Read the wheel in an isolated environment, using the Python distribution name
+from `[project].name`:
+
+```console
+uvx --with dist/my_package-0.1.0-py3-none-any.whl \
+  agent-plugins read my-package
+```
+
+Confirm the reported distribution version, plugin metadata, bounded inventory,
+and skill instructions. Use
+[artifact verification](references/verify-artifacts.md) for exhaustive inventory
+comparison. Put the public bootstrap in the package README:
+
+```console
+uvx --with my-package agent-plugins read my-package
+```
+
+Keep `agent-plugins` in `[build-system].requires` for packaging. Add it to
+`[project].dependencies` when installed Python code calls `agent_plugins`
+directly at runtime.
+
+## Choose a different build path
+
+- For Hatchling, monorepo roots, include patterns, custom backends, or an
+  externally built wheel, read
+  [build variants](references/build-variants.md).
+- For wheel, source distribution, editable, document, and Agent Skills checks,
+  read [artifact verification](references/verify-artifacts.md).
+- For `mcp.json`, read the
+  [MCP integration guide](https://peter-gy.github.io/agent-plugins/integrations/mcp-servers).
+- For reverse-domain client directories, read the
+  [client extension guide](https://peter-gy.github.io/agent-plugins/integrations/client-extensions).
+
+Use the `agent-plugins` skill when the repository work is complete and the task
+becomes consuming an installed package's instructions or resources.

agent_plugins-0.2.3/.agent-plugin/skills/package-agent-plugin/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Package an Agent Plugin"
+  short_description: "Add Agent Plugin packaging to a Python project"
+  default_prompt: "Use $package-agent-plugin to add version-matched agent instructions to this Python package."

agent_plugins-0.2.3/.agent-plugin/skills/package-agent-plugin/references/build-variants.md

@@ -0,0 +1,77 @@
+# Build variants
+
+## Hatchling
+
+Wrap an existing Hatchling project with the bundled adapter:
+
+```toml
+[build-system]
+requires = ["agent-plugins", "hatchling"]
+build-backend = "agent_plugins.build.hatchling"
+
+[tool.agent-plugins]
+root = "."
+```
+
+The adapter preserves the delegate's wheel, source distribution, and editable
+behavior while adding the selected Agent Plugin and installation marker.
+
+## Monorepo roots
+
+Resolve `root` relative to the `pyproject.toml` that owns the build. For this
+layout, the Python package points back to the repository plugin root:
+
+```text
+repository/
+|-- plugin.json
+|-- skills/
+`-- packages/
+    `-- python/
+        `-- pyproject.toml
+```
+
+```toml
+[tool.agent-plugins]
+root = "../.."
+```
+
+## Additional selected files
+
+The build always 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 remain inside the plugin root and match at least one
+filesystem entry. A matched directory contributes its regular files.
+
+## Prebuilt wheels
+
+When another backend owns the wheel, attach the configured Agent Plugin after
+that build:
+
+```console
+agent-plugins attach-wheel dist/my_package-0.1.0-py3-none-any.whl \
+  --project .
+```
+
+The command atomically replaces the input wheel after the complete attached
+artifact succeeds. Use `--output-dir` to preserve the source wheel. The Python
+API exposes the same operation:
+
+```python
+import agent_plugins as ap
+
+result = ap.attach_wheel(
+    "dist/my_package-0.1.0-py3-none-any.whl",
+    project=".",
+)
+print(result.output)
+```
+
+A custom delegate must expose wheel, source distribution, and editable build
+hooks together with their corresponding `get_requires_for_build_*` hooks.

agent_plugins-0.2.3/.agent-plugin/skills/package-agent-plugin/references/verify-artifacts.md

@@ -0,0 +1,36 @@
+# Verify package artifacts
+
+Treat source and installed inspection as two views of the same selected plugin:
+
+```python
+import agent_plugins as ap
+
+source = ap.Plugin.from_project(".")
+installed = ap.locate("my-package")
+
+assert source.manifest.name == installed.manifest.name
+assert [path.relative_to(source.path) for path in source.files] == [
+    path.relative_to(installed.path) for path in installed.files
+]
+```
+
+Verify every release boundary:
+
+1. Run `agent-plugins plan PROJECT` and inspect every selected path.
+2. Build a wheel and source distribution through the configured adapter, or
+   attach the plugin to the externally built wheel.
+3. Rebuild a wheel from the source distribution.
+4. Install the direct and rebuilt wheels in clean environments.
+5. Run `agent-plugins read my-package` against both installed wheels.
+6. Install the project as editable and confirm `locate()` resolves the authored
+   plugin root.
+7. Compare source and installed file inventories and bytes.
+8. Access `manifest.name`, every `skill.source`, and `mcp.servers` when present
+   to execute supported document validation.
+9. Confirm each `skill.file("SKILL.md")` and referenced resource is selected.
+10. Run an Agent Skills validator against every authored skill directory.
+
+Let `AgentPluginError` fail missing configuration, unusable paths, or discovery.
+Let `ValidationError` fail invalid manifest, MCP, or skill documents. Artifact
+verification should exercise the CLI through the installed console script as
+well as the Python API.

{agent_plugins-0.2.1 → agent_plugins-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-plugins
-Version: 0.2.1
+Version: 0.2.3
 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>
@@ -12,7 +12,7 @@ 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-Dist: tomli>=1.0.3 ; 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
@@ -48,6 +48,19 @@ Description-Content-Type: text/markdown
 
 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.
 
+## Read the bundled guidance
+
+Run `agent-plugins` without arguments to read its own installed plugin:
+
+```console
+uvx agent-plugins
+```
+
+The output contains two version-matched skills. `agent-plugins` explains how to
+read instructions from Python packages that already ship an Agent Plugin.
+`package-agent-plugin` explains how to add Agent Plugin packaging to a Python
+project.
+
 ## Package your plugin
 
 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`:
@@ -77,20 +90,27 @@ Attachment updates the wheel in place. Pass `--output-dir` to preserve the input
 
 ## Inspect an installed plugin
 
-Install `agent-plugins` in the environment you want to inspect. The package includes its own Agent Skill:
+Load the complete version-matched guidance shipped by a package:
 
 ```console
-pip install agent-plugins
+uvx --with my-package agent-plugins read my-package
 ```
 
+The first `my-package` tells uv which distribution to install. The second
+identifies the installed Agent Plugin to read.
+
+Use the Python API when the package is already installed in the current
+environment:
+
 ```python
 import agent_plugins as ap
 
 plugin = ap.locate("agent-plugins")
-skill = plugin.skill("agent-plugins")
+consumer_skill = plugin.skill("agent-plugins")
+packaging_skill = plugin.skill("package-agent-plugin")
 
-print(skill.source)
-print(skill.file("SKILL.md"))
+print(consumer_skill.source)
+print(packaging_skill.source)
 ```
 
 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.

{agent_plugins-0.2.1 → agent_plugins-0.2.3}/README.md

@@ -27,6 +27,19 @@
 
 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.
 
+## Read the bundled guidance
+
+Run `agent-plugins` without arguments to read its own installed plugin:
+
+```console
+uvx agent-plugins
+```
+
+The output contains two version-matched skills. `agent-plugins` explains how to
+read instructions from Python packages that already ship an Agent Plugin.
+`package-agent-plugin` explains how to add Agent Plugin packaging to a Python
+project.
+
 ## Package your plugin
 
 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`:
@@ -56,20 +69,27 @@ Attachment updates the wheel in place. Pass `--output-dir` to preserve the input
 
 ## Inspect an installed plugin
 
-Install `agent-plugins` in the environment you want to inspect. The package includes its own Agent Skill:
+Load the complete version-matched guidance shipped by a package:
 
 ```console
-pip install agent-plugins
+uvx --with my-package agent-plugins read my-package
 ```
 
+The first `my-package` tells uv which distribution to install. The second
+identifies the installed Agent Plugin to read.
+
+Use the Python API when the package is already installed in the current
+environment:
+
 ```python
 import agent_plugins as ap
 
 plugin = ap.locate("agent-plugins")
-skill = plugin.skill("agent-plugins")
+consumer_skill = plugin.skill("agent-plugins")
+packaging_skill = plugin.skill("package-agent-plugin")
 
-print(skill.source)
-print(skill.file("SKILL.md"))
+print(consumer_skill.source)
+print(packaging_skill.source)
 ```
 
 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.

{agent_plugins-0.2.1 → agent_plugins-0.2.3}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "agent-plugins"
-version = "0.2.1"
+version = "0.2.3"
 description = "Ship Agent Plugins with Python packages and inspect their installed files"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 requires-python = ">=3.10,<3.15"
-dependencies = ["tomli==2.3.1; python_version < '3.11'"]
+dependencies = ["tomli>=1.0.3; python_version < '3.11'"]
 classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -30,7 +30,7 @@ agent-plugins = "agent_plugins._cli:main"
 
 [build-system]
 requires = [
-    "tomli==2.3.1; python_version < '3.11'",
+    "tomli>=1.0.3; python_version < '3.11'",
     "uv_build==0.12.2",
 ]
 build-backend = "agent_plugins.build.uv_build"

{agent_plugins-0.2.1 → agent_plugins-0.2.3}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "agent-plugins"
-version = "0.2.1"
+version = "0.2.3"
 description = "Ship Agent Plugins with Python packages and inspect their installed files"
 readme = "README.md"
 license = "Apache-2.0"
@@ -10,7 +10,7 @@ authors = [
 ]
 requires-python = ">=3.10,<3.15"
 dependencies = [
-    "tomli==2.3.1; python_version < '3.11'",
+    "tomli>=1.0.3; python_version < '3.11'",
 ]
 classifiers = [
     "Programming Language :: Python :: 3.10",
@@ -31,7 +31,7 @@ agent-plugins = "agent_plugins._cli:main"
 
 [build-system]
 requires = [
-    "tomli==2.3.1; python_version < '3.11'",
+    "tomli>=1.0.3; python_version < '3.11'",
     "uv_build==0.12.2",
 ]
 build-backend = "agent_plugins.build.uv_build"

{agent_plugins-0.2.1 → agent_plugins-0.2.3}/src/agent_plugins/_cli.py

@@ -12,19 +12,25 @@ from ._build.plan import BuildPlan, build_plan
 from ._build.wheel import WheelAttachment, attach_wheel
 from ._discovery import installed, locate
 from ._errors import AgentPluginError
+from ._read import render_read
 
 
 def main(argv: Sequence[str] | None = None) -> int:
     """Run the Agent Plugins command-line interface."""
-    arguments = _parser().parse_args(argv)
+    values = tuple(sys.argv[1:] if argv is None else argv)
+    arguments = _parser().parse_args(values or ("read", "agent-plugins"))
     try:
         if arguments.command == "list":
             _list_plugins(as_json=arguments.json)
         elif arguments.command == "locate":
             print(locate(arguments.distribution).path)
+        elif arguments.command == "read":
+            sys.stdout.write(
+                render_read(arguments.distribution, skill_name=arguments.skill)
+            )
         elif arguments.command == "plan":
             _print_plan(build_plan(arguments.project), as_json=arguments.json)
-        else:
+        elif arguments.command == "attach-wheel":
             result = attach_wheel(
                 arguments.wheel,
                 project=arguments.project,
@@ -37,6 +43,8 @@ def main(argv: Sequence[str] | None = None) -> int:
                     f"{signature.as_posix()}",
                     file=sys.stderr,
                 )
+        else:  # pragma: no cover - argparse owns the command choices
+            raise AssertionError(f"Unexpected command: {arguments.command!r}")
     except AgentPluginError as error:
         print(f"agent-plugins: error: {error}", file=sys.stderr)
         return 1
@@ -46,7 +54,7 @@ def main(argv: Sequence[str] | None = None) -> int:
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="agent-plugins",
-        description="Package and inspect Agent Plugins in Python distributions.",
+        description="Read, package, and inspect Agent Plugins in Python distributions.",
     )
     commands = parser.add_subparsers(dest="command", required=True)
 
@@ -64,6 +72,15 @@ def _parser() -> argparse.ArgumentParser:
         "distribution", help="Installed Python distribution name."
     )
 
+    read_parser = commands.add_parser(
+        "read",
+        help="Print one installed plugin and its Agent Skill instructions.",
+    )
+    read_parser.add_argument("distribution", help="Installed Python distribution name.")
+    read_parser.add_argument(
+        "--skill", help="Print one named skill instead of every packaged skill."
+    )
+
     plan_parser = commands.add_parser(
         "plan", help="List files selected by [tool.agent-plugins]."
     )

{agent_plugins-0.2.1 → agent_plugins-0.2.3}/src/agent_plugins/_discovery.py

@@ -18,6 +18,10 @@ def locate(distribution_name: str) -> Plugin:
     Raises:
         AgentPluginError: The distribution has no usable Agent Plugin marker.
     """
+    return _locate(distribution_name)[1]
+
+
+def _locate(distribution_name: str) -> tuple[metadata.Distribution, Plugin]:
     if not distribution_name:
         raise AgentPluginError("A distribution name is required")
 
@@ -28,7 +32,7 @@ def locate(distribution_name: str) -> Plugin:
             f"Python distribution {distribution_name!r} is not installed"
         ) from None
 
-    return _root(distribution, distribution_name)
+    return distribution, _root(distribution, distribution_name)
 
 
 def installed() -> dict[str, Plugin]: