peter-gy/agent-plugins / skills/package-agent-plugin
package-agent-plugin
UnverifiedPackage 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 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:
my-package/
|-- plugin.json
|-- pyproject.toml
|-- skills/
| `-- my-package/
| `-- SKILL.md
`-- src/
`-- my_package/
Create plugin.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:
[build-system]
requires = ["agent-plugins", "uv_build"]
build-backend = "agent_plugins.build.uv_build"
[tool.agent-plugins]
root = "."
Preview the exact selection, then build:
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:
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 for exhaustive inventory comparison. Put the public bootstrap in the package README:
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:
# 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 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.
- For wheel, source distribution, editable, document, and Agent Skills checks, read artifact verification.
- For
mcp.json, read the MCP integration guide. - For reverse-domain client directories, read the client extension guide.
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 for additional packaging and integration guidance.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |