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

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

@@ -0,0 +1,132 @@
+---
+name: agent-plugins
+description: Read version-matched agent briefings and resources from installed Python distributions. Use when a package README points to agent-plugins, a Python host exposes packaged guidance, or a task needs plugin discovery, linked resources, or installation diagnostics. For adding Agent Plugin packaging to a project, use package-agent-plugin.
+---
+
+# Read installed Agent Plugins
+
+Read the instructions shipped with the Python installation that will execute
+the task. A briefing combines distribution identity, environment guidance,
+plugin inventory, and complete skill instructions. The host supplies execution
+tools, dependency management, and runtime connections.
+
+## Choose the entrypoint
+
+If the package is already installed, read its briefing in that Python
+environment:
+
+```python
+import agent_plugins as ap
+
+print(ap.read("my-package"))
+```
+
+`ap.read()` returns a string and selects the skill whose directory name matches
+the distribution argument exactly. Pass `skill="use-my-package"` when the
+workflow has another name. An unavailable skill raises `AgentPluginError` and
+lists the available names. Use the host's captured `help(module)` output when
+a package exposes the same briefing through an agent module.
+
+When starting from a README before setting up an execution environment, run:
+
+```console
+uvx --with my-package agent-plugins read my-package
+```
+
+The requirement after `--with` selects what uv installs. The final argument
+identifies the installed distribution to inspect. Pin the requirement, such as
+`'my-package==1.2.3'`, when the task requires a particular release.
+
+The CLI includes every packaged skill by default. Select one with
+`--skill NAME`. Follow the workflows applicable to the request. Running
+`uvx agent-plugins` with no arguments reads this package's consumer and
+packaging skills.
+
+## Use the execution environment
+
+Check the briefing's distribution version and interpreter before using its
+examples. `uvx` uses an isolated, disposable tool environment. Its resource
+paths can remain readable while cached, but the project or notebook may have
+a different installation or filesystem.
+
+Install dependencies through the target project's or host's package manager,
+preserving its version policy. Then read that installation's briefing. From a
+terminal, bind the CLI to the intended interpreter:
+
+```console
+/path/to/environment/bin/python -m agent_plugins read my-package
+```
+
+In a remote kernel or service, execute `ap.read()` there. Reuse the briefing
+while that environment and installation remain unchanged. If a package's
+module help already supplied the applicable skill, continue with its workflow.
+Rediscover after switching environments or installations. Restart a process
+that still holds imports from a replaced package.
+
+Package availability and runtime readiness are separate. Follow the selected
+workflow's connection, activation, and verification steps before treating a
+browser, service, device, or other host as ready.
+
+## Read linked resources
+
+Relative links are resolved from the skill directory. When the agent cannot
+read that filesystem directly, retrieve the text through Python in its owning
+environment:
+
+```python
+import agent_plugins as ap
+
+plugin = ap.locate("my-package")
+skill = plugin.skill("my-package")
+print(skill.tree())
+```
+
+Choose a resource named by the skill. For a packaged `references/api.md`:
+
+```python
+print(skill.file("references/api.md").read_text(encoding="utf-8"))
+```
+
+`skill.file()` checks selected-file membership and containment. Reacquire the
+handle in each execution if the host discards local bindings between calls.
+Read additional resources at the decision points specified by the workflow.
+`skill.source` returns the full instruction file, and `skill.body` omits its
+frontmatter when raw text is needed instead of a briefing.
+
+Use published documentation and its `llms.txt` index for broader examples and
+reference. Check that an online API matches the active installation. A source
+checkout describes that checkout and may differ from an installed release.
+
+## Inspect or recover
+
+| Task | Operation |
+| --- | --- |
+| Find plugins in this interpreter | `ap.installed()` |
+| Inspect one plugin's selected files | `ap.locate("my-package").tree()` |
+| Discover its skill names | `[skill.name for skill in plugin.skills]` |
+| Inspect plugin metadata | `plugin.manifest` |
+| Inspect MCP configuration | `plugin.mcp` |
+| List installed plugins from a terminal | `agent-plugins list --json` |
+| Print one installed plugin root | `agent-plugins locate my-package` |
+
+Pass the Python distribution name to `read()` and `locate()`. The manifest
+plugin name and Python import name can differ from it.
+
+For an absent distribution or unusable plugin, correct the target installation
+before retrying. For an unavailable skill, select a listed structural name.
+`ValidationError` identifies an invalid plugin document. Preserve that
+diagnostic when the packaged files need repair.
+
+Briefings summarize MCP names and transports while leaving configured commands,
+arguments, environment values, URLs, and headers out of the output. The host
+owns component activation and execution permissions.
+
+Use `agent-plugins --help` or `agent-plugins COMMAND --help` for CLI syntax.
+Success writes to stdout. Expected operational failures return status `1`
+with a diagnostic on stderr. Argument errors return status `2`.
+
+For project packaging, build planning, or wheel attachment, read the
+`package-agent-plugin` skill.
+
+Use the [documentation index](https://peter-gy.github.io/agent-plugins/llms.txt)
+for additional API and integration guidance.

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

@@ -0,0 +1,150 @@
+---
+name: package-agent-plugin
+description: Package version-matched agent briefings with a Python project. Use when authoring core skills and references, exposing guidance through Python module help, configuring a build adapter, attaching a plugin to a wheel, or verifying installed handoffs. For consuming an installed package's instructions, use agent-plugins.
+---
+
+# Package an Agent Plugin
+
+Package instructions beside the Python code they describe so the library and
+its Agent Plugin share one release. Author one compact core skill that works
+from a CLI briefing, Python module help, or a directly loaded skill file.
+
+## Design the briefing
+
+Start from a fresh agent's task: what the package enables, which host or extras
+it requires, the first complete action, how to verify success, and where to
+read more. Include every import and binding needed by the first example.
+
+Keep package concepts, workflow choices, essential invariants, and verification
+in the core skill. Put substantial setup variants and specialized workflows in
+linked references, with a condition explaining when each is needed. Let the
+generated briefing supply installation identity and resource-access guidance.
+Rereading the current skill should not be a prerequisite for following it.
+
+Read [briefing design](references/briefings.md) when authoring the skill or
+adding a Python help entrypoint. It covers ownership, a reusable skill shape,
+documentation links, and fresh-agent acceptance scenarios.
+
+## 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/
+|   `-- 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."
+}
+```
+
+Name the core skill `my-package` to match `[project].name`. This lets
+`ap.read("my-package")` select it by default. A task-specific skill can use
+another name and be selected explicitly.
+
+Create `skills/my-package/SKILL.md` with `name` and a discriminating
+`description` in YAML frontmatter, followed by the package's shortest complete
+workflow. Use real public APIs and expected results from the project.
+
+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, with a lower bound that includes the APIs used.
+
+## Expose the same briefing in Python
+
+Use `ap.read()` in the package's agent module to deliver its core skill through
+standard Python help:
+
+```python
+# src/my_package/agent.py
+import agent_plugins as _ap
+
+__doc__ = _ap.read("my-package")
+```
+
+The caller runs `import my_package.agent` followed by `help(my_package.agent)`.
+`help()` prints the briefing and returns `None`. Use `print(ap.read(...))` when
+the host needs explicit text output. Pass `skill="task-name"` for a differently
+named core skill. Host capability registration remains the host's contract.
+
+Keep ordinary package imports independent of this optional help module. Give
+the agent module a small introspection surface and inspect its actual
+`help()` output, since exported classes can add extensive API documentation.
+Keep detailed signatures on the corresponding API objects. See
+[briefing design](references/briefings.md#python-module-help) for runtime access
+and documentation ownership.
+
+Verify both the CLI and Python briefing from the installed wheel. A successful
+read establishes access to instructions. Exercise the first workflow in its
+required host to establish runtime readiness and a verified result.
+
+## 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.
+
+Use the [documentation index](https://peter-gy.github.io/agent-plugins/llms.txt)
+for additional packaging and integration guidance.

agent_plugins-0.2.4/.agent-plugin/skills/package-agent-plugin/references/briefings.md

@@ -0,0 +1,143 @@
+# Design package briefings
+
+An independently loaded skill must give a fresh agent enough information to
+choose a workflow, execute its first action, verify the result, and find the
+next relevant resource. CLI and Python help should present the same authored
+core, with environment context supplied by `agent-plugins`.
+
+## Assign each surface an owner
+
+| Surface | Content |
+| --- | --- |
+| Package README | Bootstrap command and the already-installed Python route |
+| Generated briefing | Distribution version, interpreter, resource location, documentation links, and selected skill source |
+| Core skill | Applicability, package concepts, prerequisites, workflow, and verification |
+| Skill references | Conditional setup, specialized workflows, and detailed recovery |
+| API docstrings | Signatures, inputs, returns, side effects, and operation semantics |
+| Project instructions | Repository or authored-project conventions |
+| Published docs | Broader guides, examples, and reference pages |
+
+Package-specific host requirements and optional extras belong with the
+workflow that needs them. The execution host or project manager owns dependency
+installation and version policy. An importable agent module already has its
+base package installed, so its help should route to additional setup only when
+the selected operation requires it.
+
+Distinguish instructions being available, a package being installed in the
+execution environment, and the required runtime being connected and ready.
+Describe the check that establishes each relevant transition.
+
+## Shape the core skill
+
+Use this outline when the package has several workflows. Collapse sections
+when a smaller skill can convey the same contract:
+
+```text
+Frontmatter: name and concrete activation conditions
+Purpose: outcome, essential objects, and their ownership
+Choose: task-to-workflow routes and their prerequisites
+Start: smallest complete example, including imports and bindings
+Verify: observable success and the main misleading success signal
+Continue: conditional references, recovery, and published documentation
+```
+
+Prefer a compact core, often around 100–200 lines. Length follows the complete
+workflow rather than a quota. Move substantial conditional material into
+focused `references/` files and link it at the decision point where it is
+needed. Keep essential correctness constraints beside the example they govern.
+
+Write the core for direct loading as well as generated briefings. A first
+example must not depend on a variable created by module help, a prior task, or
+another execution call. Repeat short imports where they make an example
+independent. For hosts that discard scratch bindings, explain how to reacquire
+handles and which identities or results must survive between calls.
+
+Do not require the agent to read the skill it is already following. Reuse
+loaded instructions for the same environment and installation. Route back to
+discovery when the environment or installation changes or an API mismatch
+requires checking the source of the instructions.
+
+Use relative links beneath the skill root and resolve packaged resources with
+`Skill.file()`. Absolute paths in a briefing describe its owning installation.
+They can be inaccessible from another host or disappear with a disposable
+environment. Provide a Python resource-access route for remote execution.
+
+Keep additional task skills independently selectable when their activation
+conditions differ. A general package capability should route to a specialized
+workflow only when the user's request calls for it.
+
+## Python module help
+
+The packaging skill's minimal `agent.py` example sets `__doc__` from
+`ap.read("my-package")`. It reads the installed core when that module is
+imported. Keep it out of the package's ordinary import path. Restart the host
+after replacing an already imported installation.
+
+`ap.read()` returns one Markdown string. Omitted `skill` uses the distribution
+argument exactly. An explicit `skill` selects a structural directory name.
+The CLI uses the same renderer but includes all skills unless `--skill` is
+provided. Both entrypoints preserve the selected instruction source.
+
+If callers need resource handles, expose small accessors over the public API:
+
+```python
+import agent_plugins as _ap
+
+
+def agent_plugin() -> _ap.Plugin:
+    return _ap.locate("my-package")
+
+
+def agent_skill() -> _ap.Skill:
+    return agent_plugin().skill("my-package")
+```
+
+Callers can then read a linked file inside the execution host with
+`agent_skill().file("references/setup.md").read_text(encoding="utf-8")`, when
+that resource is packaged. Add accessors when consumers need them, and retain
+host adapters that implement package-specific operations.
+
+Inspect actual `help(module)` output. Python can append documentation for
+exported functions and classes, even when the module docstring is short.
+Keep initial help focused and route detailed introspection to the relevant
+objects or submodules. Check that help reads instructions without connecting
+services, mounting components, or performing the example's operations.
+
+## Publish documentation links
+
+Declare documentation URLs in Python package metadata:
+
+```toml
+[project.urls]
+Documentation = "https://example.org/my-package/"
+"Documentation Index" = "https://example.org/my-package/llms.txt"
+```
+
+`agent-plugins` includes these two labels in generated briefings. The
+`Documentation Index` label is a package-authoring convention. Use the actual
+index URL when one is published, and verify its linked destinations as part of
+the documentation build. A new manifest property is unnecessary.
+
+Keep a short documentation link in the core skill too, so it works when loaded
+independently of Python metadata. Load specific linked pages as needed. Check
+online APIs against the installed version. A development checkout describes
+that checkout and may differ from a released installation.
+
+## Verify the handoff
+
+Exercise the entrypoints an agent will actually use:
+
+1. From a README, run the isolated CLI bootstrap and follow one linked resource.
+   Confirm the output distinguishes that installation from the execution host.
+2. In a project with an existing installation, read through its interpreter and
+   verify the reported version and resource origin.
+3. Through the intended Python host, read module help and retrieve a reference
+   using Python when direct filesystem access is unavailable.
+4. Load `SKILL.md` directly and follow its first example using fresh bindings.
+5. Continue a related task in the same environment and verify that the routing
+   advances to relevant work instead of requiring repeated discovery.
+
+Test required runtime readiness and the example's expected result separately
+from successful imports and resource reads. Keep failures actionable: an absent
+package requires installation, an unknown skill requires selecting an available
+name, and an unavailable runtime requires its host's connection workflow.

{agent_plugins-0.2.3 → agent_plugins-0.2.4}/.agent-plugin/skills/package-agent-plugin/references/verify-artifacts.md

@@ -21,7 +21,9 @@ Verify every release boundary:
    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.
+5. Run `agent-plugins read my-package` and `ap.read("my-package")` against both
+   installed wheels. Pass an explicit skill name when it differs from the
+   distribution name. Compare the Python briefing with CLI `--skill` output.
 6. Install the project as editable and confirm `locate()` resolves the authored
    plugin root.
 7. Compare source and installed file inventories and bytes.
@@ -34,3 +36,7 @@ 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.
+
+When the package exposes module help, inspect its captured output and follow
+the [briefing handoff scenarios](briefings.md#verify-the-handoff). Confirm that
+each referenced setup or workflow file is available in the installed inventory.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-plugins
-Version: 0.2.3
+Version: 0.2.4
 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>
@@ -15,6 +15,7 @@ Classifier: Typing :: Typed
 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: Documentation Index, https://peter-gy.github.io/agent-plugins/llms.txt
 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
@@ -105,14 +106,15 @@ environment:
 ```python
 import agent_plugins as ap
 
-plugin = ap.locate("agent-plugins")
-consumer_skill = plugin.skill("agent-plugins")
-packaging_skill = plugin.skill("package-agent-plugin")
-
-print(consumer_skill.source)
-print(packaging_skill.source)
+print(ap.read("agent-plugins"))
+print(ap.read("agent-plugins", skill="package-agent-plugin"))
 ```
 
+`read()` returns a briefing for the same-name skill by default. Pass `skill=`
+for another workflow. The CLI reads all packaged skills unless `--skill` is
+provided. `uvx` uses an isolated tool environment, so read through the target
+interpreter when working with an existing installation.
+
 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.
 
 ## Documentation

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

@@ -84,14 +84,15 @@ environment:
 ```python
 import agent_plugins as ap
 
-plugin = ap.locate("agent-plugins")
-consumer_skill = plugin.skill("agent-plugins")
-packaging_skill = plugin.skill("package-agent-plugin")
-
-print(consumer_skill.source)
-print(packaging_skill.source)
+print(ap.read("agent-plugins"))
+print(ap.read("agent-plugins", skill="package-agent-plugin"))
 ```
 
+`read()` returns a briefing for the same-name skill by default. Pass `skill=`
+for another workflow. The CLI reads all packaged skills unless `--skill` is
+provided. `uvx` uses an isolated tool environment, so read through the target
+interpreter when working with an existing installation.
+
 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.
 
 ## Documentation

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

@@ -1,6 +1,6 @@
 [project]
 name = "agent-plugins"
-version = "0.2.3"
+version = "0.2.4"
 description = "Ship Agent Plugins with Python packages and inspect their installed files"
 readme = "README.md"
 license = "Apache-2.0"
@@ -22,6 +22,7 @@ email = "dev.petergy@gmail.com"
 
 [project.urls]
 Documentation = "https://peter-gy.github.io/agent-plugins/"
+"Documentation Index" = "https://peter-gy.github.io/agent-plugins/llms.txt"
 Issues = "https://github.com/peter-gy/agent-plugins/issues"
 Source = "https://github.com/peter-gy/agent-plugins"
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "agent-plugins"
-version = "0.2.3"
+version = "0.2.4"
 description = "Ship Agent Plugins with Python packages and inspect their installed files"
 readme = "README.md"
 license = "Apache-2.0"
@@ -23,6 +23,7 @@ classifiers = [
 
 [project.urls]
 Documentation = "https://peter-gy.github.io/agent-plugins/"
+"Documentation Index" = "https://peter-gy.github.io/agent-plugins/llms.txt"
 Issues = "https://github.com/peter-gy/agent-plugins/issues"
 Source = "https://github.com/peter-gy/agent-plugins"
 

{agent_plugins-0.2.3 → agent_plugins-0.2.4}/src/agent_plugins/__init__.py

@@ -5,6 +5,7 @@ from ._build.wheel import WheelAttachment, attach_wheel
 from ._discovery import installed, locate
 from ._errors import AgentPluginError
 from ._plugin import Plugin
+from ._read import read
 from ._schema import (
     Author,
     Manifest,
@@ -40,4 +41,5 @@ __all__ = [
     "build_plan",
     "installed",
     "locate",
+    "read",
 ]

{agent_plugins-0.2.3 → agent_plugins-0.2.4}/src/agent_plugins/_read.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import re
+import sys
 from importlib.metadata import Distribution
 
 from ._discovery import _locate
@@ -12,6 +13,30 @@ from ._schema.models import Author
 from ._skill import Skill
 
 
+def read(distribution_name: str, *, skill: str | None = None) -> str:
+    """Return a Markdown briefing for one installed Agent Skill.
+
+    Args:
+        distribution_name: Python distribution to inspect in this interpreter.
+        skill: Structural skill name. Omitted or None uses distribution_name
+            exactly, including its spelling.
+
+    The briefing includes package metadata, environment and resource guidance,
+    a bounded plugin inventory, and the complete selected skill source. It
+    returns text without printing, importing the target package, or activating
+    its components.
+
+    Raises:
+        AgentPluginError: The distribution, plugin, or selected skill is
+            unavailable or unusable.
+        ValidationError: A selected plugin document is invalid.
+    """
+    return render_read(
+        distribution_name,
+        skill_name=distribution_name if skill is None else skill,
+    )
+
+
 def render_read(distribution_name: str, *, skill_name: str | None = None) -> str:
     """Return a getting-started briefing for one installed Agent Plugin."""
     distribution, plugin = _locate(distribution_name)
@@ -30,6 +55,7 @@ def _markdown(
         f"# Agent Plugin: {_code(manifest.name)}",
         "",
         f"Python distribution: {_code(f'{distribution_name}=={distribution.version}')}",
+        f"Python interpreter: {_code(sys.executable)}",
         f"Installed root: {_code(str(plugin.path))}",
     ]
     summary = distribution.metadata["Summary"]
@@ -47,6 +73,18 @@ def _markdown(
         lines.append(f"Homepage: {_one_line(manifest.homepage)}")
     if manifest.repository:
         lines.append(f"Repository: {_one_line(manifest.repository)}")
+    for project_url in distribution.metadata.get_all("Project-URL") or ():
+        label, separator, url = project_url.partition(",")
+        if (
+            separator
+            and url.strip()
+            and label.strip().casefold()
+            in {
+                "documentation",
+                "documentation index",
+            }
+        ):
+            lines.append(f"{_one_line(label)}: {_one_line(url)}")
     if manifest.license:
         lines.append(f"License: {_one_line(manifest.license)}")
     if manifest.keywords:
@@ -56,6 +94,23 @@ def _markdown(
 
     lines.extend(
         (
+            "",
+            (
+                "This briefing describes the installation in the Python environment "
+                "shown here. Resource paths belong to that environment. If invoked "
+                "through uvx, the package is in an isolated, disposable tool "
+                "environment, not installed into your project or notebook. Cached "
+                "paths may remain readable locally but may be inaccessible from "
+                "another execution host."
+            ),
+            "",
+            (
+                "Before running package code in another environment, read the "
+                "briefing from that installation. Reuse loaded instructions while "
+                "the environment and installation remain unchanged. The host owns "
+                "dependency installation and runtime connections. Reading these "
+                "instructions does not establish runtime readiness."
+            ),
             "",
             (
                 "Complete installed Agent Skill instructions follow. Resolve relative "
@@ -67,8 +122,9 @@ def _markdown(
             _fenced_block(plugin.tree(), language="text"),
             "",
             (
-                "The inventory is bounded. Inspect the installed root shown above when "
-                "a skill routes to a deeper resource."
+                "The inventory is bounded. Resolve linked resources through "
+                "agent_plugins.locate() in the owning Python environment, or read "
+                "them beneath the installed root when its filesystem is accessible."
             ),
         )
     )

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

@@ -1,103 +0,0 @@
----
-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/package-agent-plugin/SKILL.md

@@ -1,108 +0,0 @@
----
-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.