Plugins

Understand what a plugin package holds, and what kagent does with one when an agent starts.

A plugin packagePlugin packageA bundle that an AgentTemplate attaches with spec.plugins, carrying skills and optionally declaring Model Context Protocol servers. Packages follow the Agent Plugins format, which kagent consumes rather than defines.Learn more is a bundle that an AgentTemplate attaches with spec.plugins. The package carries skillsSkillA packaged piece of know-how that an agent can pick up: a directory holding a SKILL.md file of instructions, plus any scripts or reference files those instructions use. An AgentTemplate attaches skills by naming where each one comes from.Learn more and can also declare Model Context ProtocolModel Context ProtocolAn open protocol for exposing tools and resources to a model. kagent reaches an MCP server through a RemoteMCPServer resource, and an AgentTemplate binds individual tools from it.Learn more (MCP) servers. Packages follow the Agent Plugins 1.0.0 format, which kagent consumes rather than defines. This page covers what a package holds and how kagent handles it. To understand how to attach a plugin package with an AgentTemplate, see Skills.

What a package holds

A package root can hold up to three things.

plugin.json (required): The manifest that names the package.
skills/: One subdirectory per skill, each holding a SKILL.md file at its root.
mcp.json: Declares MCP servers that kagent adds to the agent’s tools.

kagent reads name from the manifest and ignores the rest, so a package that carries version, description, author, homepage, repository, license, keywords, or extensions is accepted, but none of those fields change what the agent gets. The manifest’s $schema must be exactly https://agent-plugins.org/schemas/1.0.0/plugin.schema.json.

Note

kagent compares that $schema value literally. It does not fetch the schema or validate the document against it, so a manifest that names the right schema and holds the wrong shape is rejected by the decoder rather than by schema validation.

MCP servers

A package that includes mcp.json contributes MCP servers to every agent that enables it, alongside any bound directly on the AgentTemplate (see About tools). The file declares an mcpServers object, keyed by server name, and its $schema must be exactly https://agent-plugins.org/schemas/1.0.0/mcp.schema.json.

Each server names a transport in its type field, and the transport determines which other fields are allowed.

Transport	Fields	Description
`stdio`	`command`, `args`, `env`, `cwd`	Runs a process inside the agent’s sandbox. Specifying `url` or `headers` is rejected.
`streamable-http`	`url`, `headers`	Calls a remote server. Specifying `command`, `args`, `env`, or `cwd` is rejected.
`sse`	`url`, `headers`	Calls a remote server over Server-Sent Events. Accepts the same fields as `streamable-http`.

kagent enforces several rules on these servers, and each one exists to keep a package from reaching outside itself.

A stdio command must be either a bare name resolved on the sandbox’s path, or a package-relative path beginning with ./. A command holding a path separator any other way or containing whitespace is rejected.
A cwd must be package-relative or written with the ${PLUGIN_ROOT} or ${PLUGIN_DATA} variables, and it is rejected if it resolves outside the package.
A remote url must be http or https, and must not carry user information or fragments. Any host other than a loopback address must use HTTPS.
Unrecognized fields are rejected rather than ignored.

An invalid server is skipped with a log entry, and the rest of the file still loads. An mcp.json that is invalid or that names an unexpected schema is ignored in full.

Referring to package files

A stdio server often needs to run something that the package ships, or to write somewhere durable. Two variables are expanded in args, env values, and cwd.

${PLUGIN_ROOT}: The directory the package was unpacked into. Read-only in practice, and shared by every Actor of the template.
${PLUGIN_DATA}: A per-package data directory that kagent creates. Use it for anything the server writes.

kagent also sets both as environment variables on every stdio server, so a server can read them without the package declaring them. A package cannot override either one: an env block that sets PLUGIN_ROOT or PLUGIN_DATA is rejected.

Package limits

kagent measures a package after fetching it and before mounting anything. A package is rejected if it holds more than 10,000 filesystem entries or more than 100 MB of regular files. A .git directory is skipped and counts toward neither.

Every source is immutable

A skill or a plugin package changes what an agent does, so kagent only accepts artifact references that cannot shift underneath a running agent. Each source names exactly one of three kinds of artifact, and every kind must be pinned in its own way.

oci: An image reference pinned to a digest, in the form <repository>@sha256:<digest>. A tag alone is rejected, because a tag can be moved to different content later.
git: A repository URL together with a full commit identifier. An abbreviated commit, a branch, or a tag is rejected.
bucket.s3: An endpoint, bucket, and key, together with the versionId of that exact object version. A region is included where the service requires one for request signing.

Pinning has a practical consequence worth planning for. Publishing a new version means updating the AgentTemplate to name the new digest, commit, or object version, which compiles a new revision. Agents that are already running keep the content that they started with.

Skills