Private Skill Plugins

Private Skill Plugins let a workspace add declarative Agent guidance without publishing a new Multica release. V1 accepts static UTF-8 text for agent.skill.v1; it is not an npm, Node, Python, WASM, or native extension system, and Multica never runs package-manager or installation hooks from a Plugin.

The feature is intended for internal and self-hosted dogfood. Both plugins_v1 and private_plugins_v1 must be enabled to discover, upload, enable, upgrade, or roll back Private Plugins. If private_plugins_v1 is turned off after installation, existing Private Plugins remain visible in the generic Installed list so administrators can disable or uninstall them safely. Already pinned Runs remain reproducible. Turning off the base plugins_v1 flag disables all Plugin management APIs.

Create a Plugin

multica plugin init ./my-plugin \
  --key dev.example.release-notes \
  --name "Release Notes" \
  --publisher example.internal

The generated directory has one strict manifest and one Skill:

my-plugin/
├── multica.plugin.json
└── skills/
    └── example-skill/
        └── SKILL.md

multica.plugin.json uses api_version: multica.plugin/v1, kind: Plugin, a reverse-DNS metadata.key, semantic metadata.version, the V1 daemon features, and only the agent.skill.contribute requested capability. Unknown fields or capabilities are rejected. Each contribution entry must be skills/<contribution-key>/SKILL.md.

See examples/plugins/incident-triage for a complete reference that is deliberately not part of the production bundled catalog.

Validate and pack

multica plugin validate ./my-plugin
multica plugin pack ./my-plugin --output ./my-plugin-0.1.0.zip
multica plugin validate ./my-plugin-0.1.0.zip

Packing is deterministic: stable input bytes produce the same ordered ZIP and the same manifest, archive, and artifact digests. Validation rejects unsafe paths, duplicate or case-colliding paths, symlinks, executable files, binary text, undeclared contribution paths, package manifests and install/build hooks, oversized files, and package limits. The Server repeats the complete validation after upload; CLI success is never trusted as authorization or integrity evidence.

Install or update

Authenticate as a workspace owner or admin, then run:

multica plugin install ./my-plugin --workspace acme
multica plugin list --workspace acme
multica plugin status dev.example.release-notes --workspace acme

Only archive bytes are uploaded. The Server does not fetch Git or HTTP URLs, and the stored source_ref is derived from the archive digest, so local usernames and absolute paths are not retained.

The first install creates a disabled Installation. Review it in Settings → Plugins, where it is labeled Private / Unverified, then enable it for the whole workspace or selected Agents. Plugin content does not grant authority by itself: effective access remains the intersection of Kernel Policy, Agent tool permissions, Plugin Grant, Binding, and actor approval.

To publish an update, change metadata.version and install again. Releases are immutable:

• Re-uploading the same key, version, and content is idempotent.
• Reusing a key and version with different content returns a conflict.
• A new version creates a new immutable release and moves the Installation to it.
• Existing tasks and retries keep their pinned Execution Manifest and never drift.

Use Settings to roll back to an earlier stored version. Installing the source again upgrades to the new version without a Server restart or deployment.

Isolation and lifecycle

Private identity is owned by a workspace. Two workspaces may use the same manifest key and version with different artifacts, but cannot enumerate, install, bind, roll back to, or resolve each other's identities and releases. Official identity remains global and separately keyed; a Private Plugin cannot claim official trust or enter the global catalog.

Disabling a Binding removes the capability from matching new tasks. Uninstalling disables the Installation and removes it from future capability snapshots. Immutable releases and artifacts referenced by historical Runs remain available for replay; physical garbage collection is outside V1.

Workspace quotas currently allow 100 private releases and 256 MiB of validated artifact content. A failed validation, conflict, or quota check is transactional and leaves no partial identity, release, or Installation.

Troubleshooting

• Private Plugin management is not enabled: enable both plugins_v1 and private_plugins_v1 in the Server feature-flag configuration.
• Package is invalid: run multica plugin validate <path> and fix the first fail-closed diagnostic.
• Immutable registry conflict: bump metadata.version; never reuse a version for changed content.
• Incompatible release: keep host_api within the V1 host range and require both execution-manifest-v1 and agent-skill-v1.
• Installation is healthy but the Skill is absent: confirm at least one workspace or Agent Binding is enabled and that the new task matches that scope.
• Permission denied: installation, update, rollback, Binding changes, and uninstall require a workspace owner or admin.

V1 does not include remote MCP, Secrets, network grants, Git/HTTP registries, install hooks, arbitrary executable code, UI contributions, automation contributions, community distribution, publisher verification, billing, or artifact garbage collection.