agent-plugins 0.2.2__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/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.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/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.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.4/.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.4/.agent-plugin/skills/package-agent-plugin/references/verify-artifacts.md

@@ -0,0 +1,42 @@
+# 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` 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.
+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.
+
+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.2 → agent_plugins-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-plugins
-Version: 0.2.2
+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
@@ -48,6 +49,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,22 +91,30 @@ 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")
-
-print(skill.source)
-print(skill.file("SKILL.md"))
+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