Primr portable Agent Plugin
This directory is an experimental distribution artifact for the published Agent Plugins v1.0.0 specification. It packages two portable Agent Skills and Primr's local MCP server:
primrroutes free and paid company-research requests and enforces the estimate-and-approval workflow for billable runs.primr-zerocollects keyless evidence and hands research and writing to the current agent host without making Primr model API calls.mcp.jsonstarts the installedprimr mcpstdio server. Loading the server does not launch research or authorize provider spend.
Compatibility scope
The package targets the published Agent Plugins v1.0.0 specification, verified on 2026-09-13. Primr's cross-client integration remains experimental. At the time of use, consult the specification's compatible-client registry. Clients can adopt skills and MCP transports incrementally, so a registry entry does not mean that every component works in every client version.
Agent Plugins v1 standardizes exactly two portable component types: Agent
Skills and MCP servers. Primr's mcp.json uses a bare primr executable token,
so its MCP component requires Primr to be installed and discoverable through
the client's executable search rules. An unavailable MCP component does not
invalidate the packaged skills.
The server runs with cwd: "${PLUGIN_DATA}". A conformant client creates this
writable directory before launch and preserves it across plugin updates, as
required by the stdio runtime contract.
With an installed Primr package, reports, job journals, and audit logs live
under ${PLUGIN_DATA}/output/, and research intermediates under
${PLUGIN_DATA}/working/. The plugin directory is package content and need
not be writable. Use returned artifact paths and the job-scoped artifact
resources to locate deliverables; the host's shell workspace is a separate
location. An editable Primr source checkout retains its development output
root and is not the installed-package configuration tested here.
The client controls the subprocess environment and may omit ambient provider keys. Configure credentials through Primr's supported key store or the client's documented environment controls when using the paid pipeline. Do not put secrets in this portable manifest. Missing keys do not prevent keyless collection or MCP discovery.
Claude Code is not claimed as a portable-v1 client here. Primr's existing
claude-code/ plugin remains the supported Claude-specific package and is
maintained independently.
Generation and drift control
Do not edit plugin.json, mcp.json, or skills/ in this directory directly.
They are generated from pyproject.toml, claude-code/skills/primr, and the
canonical .agents/skills/primr-zero source:
uv run --no-sync python scripts/sync_agent_plugin.py
uv run --no-sync python scripts/sync_agent_plugin.py --check
The generator removes the Claude-specific argument-hint field and the
experimental Agent Skills allowed-tools field from the primr mirror.
allowed-tools is valid Agent Skills metadata, but support and preapproval
semantics vary by client, so Primr does not publish it as a portable guarantee.
The skill instructions and companion files otherwise remain byte-identical to
their source. Tests validate the generated identity, the pinned v1 JSON
schemas, Agent Skills frontmatter, path containment, package-version parity,
and source drift. An isolated installed-layout test also starts the controller
with persistent plugin data, checks readiness, and verifies storage across
plugin replacement. These checks do not certify every client or client version.
The source distribution includes this directory. The Python wheel continues to
carry the installed primr-zero resource used by primr prep; it is not a
second editable source for this plugin.
Spend boundary
Installing or loading this package does not authorize a paid Primr run. A provider-backed run still requires a fresh estimate and explicit approval. Configured API keys are capability, not consent to spend.