Plugins

A plugin is a directory of agents, skills, instructions and workflows that moves between installations as one unit. It is how you version an agent configuration in source control, promote it from staging to production, or hand it to another tenant.

Plugins load without redeploying anything. Importing one validates its contents, creates or updates the agents it defines, and writes its skills into the tenant’s skill library. The platform does not restart, and runs already in flight keep the versions they started with.

The layout

my-plugin/
  plugin.json
  agents/
    support-bot.agent.md
  skills/
    web-research/
      SKILL.md
  instructions/
    support-bot.md

Only plugin.json is required. A plugin of nothing but skills is valid, and so is one of nothing but agents.

plugin.json is the manifest:

{
  "name": "my-plugin",
  "description": "Support agents and the skills they rely on",
  "trust_tier": "untrusted"
}

name, description and trust_tier are all required. An optional version string is accepted and is informational only — the real version identity of everything inside is its content hash, so a plugin whose contents did not change produces no new versions no matter what you write there. Any other key is rejected, so a typo fails loudly instead of being ignored.

agents/*.agent.md are the agent definitions — frontmatter plus a system-prompt body, exactly as described in Agents & assistants. The filename before .agent.md is the agent’s name.

workflows/*.workflow.yaml are optional workflow definitions: groups of the plugin’s agents that answer a conversation together. See Workflows and Build your first workflow.

skills/<name>/ are skill directories, as described in Skills.

instructions/<agent-name>.md is optional always-loaded context for one agent. Unlike a skill, which the agent reads only when it decides the skill applies, an instructions file is present on every run. Use it for things that are true all the time and short enough to justify the space — house style, a standing constraint, a phrase to always end on. Anything longer or conditional belongs in a skill.

The trust tier is a property of the plugin

trust_tier sits in the manifest, not on individual agents, because it answers a question about provenance: how much do you trust whoever wrote this? Every agent the plugin defines inherits it, and it caps what those agents can do regardless of what their own tools lists ask for. See Trust tiers.

Which tiers you can assign depends on your role. Tenant roles can create untrusted plugins; trusted is reserved for platform operators. A plugin declaring a tier above your ceiling is refused at import, and the refusal names the field — this is a permission boundary, not a validation nicety, so it is not something a request can talk its way past.

Import, export, round-trip

The Plugins screen imports a plugin archive and exports any plugin back out. Export is the inverse of import: what comes out re-imports to the same content hashes, so you can round-trip a plugin through the platform without it drifting.

That property is what makes plugins usable as a deployment artefact. Export from staging, commit the archive, import into production, and the agents on both sides are provably the same configuration rather than approximately the same.

An imported archive is unpacked defensively before any of it is written: absolute paths, .. escapes, symlinks and duplicate entries are all rejected, and the size caps are enforced while reading rather than after. A malformed or hostile archive fails at extraction, before its contents reach the validator.

Limits

• 5 MB per file.
• 50 MB per plugin, total.
• Agent, skill and plugin names must be a single path-safe segment: letters, digits, ., _ and -, starting with a letter or digit, up to 100 characters.

A plugin that exceeds a limit is rejected whole. Nothing is partially imported.

Validation is the same everywhere

A plugin’s contents go through exactly the same validation as content authored in the platform’s own screens — the same frontmatter schema, the same path rules, the same size limits, the same trust-tier ceiling. There is no import path that bypasses a check the UI applies, and no UI convenience the importer is missing.

The practical consequence: if a plugin imports cleanly, its agents and skills would have saved cleanly by hand, and any error you get from an import is an error you can reproduce and fix in the editor.

Next: Collections & knowledge.