NylorunDocsBeta
BuildDefine

Plugins

Load an Agent Plugin package; its skills and MCP servers join the agent with a plugin label.

Read an Agent Plugin package and attach it with .plugin(directory):

import { Agent } from "@nylorun/agents";

export const assistant = Agent({ id: "assistant", name: "Assistant" })
  .instructions("Use the plugin tools and skills.")
  .plugin("./plugins/github");

.plugin(directory) reads the package with loadPlugin and adds what it brings to the agent:

  • its skills go into skills, and their files are uploaded with the agent manifest like .skills();
  • its MCP servers go into mcpServers, remote servers only.

Each skill and server carries plugin: { name, version }, from the package's plugin.json (version only when it has one), so the label says where each part came from. When the agent is saved, the harness section's plugins lists each plugin's label once.

"mcpServers": {
  "github": {
    "name": "github",
    "type": "streamable-http",
    "url": "https://mcp.example.com/github",
    "plugin": { "name": "github", "version": "1.2.0" }
  }
}

.plugin() reads files, so it is on the Agent from @nylorun/agents. Each call adds one plugin. Skill names are unique among the agent's skills, and server names among its servers, so two plugins, or a plugin and the agent, cannot declare the same skill or the same server.

As a folder

In an agent manifest, a plugin vendored under plugins/<name>/ is folded in the same way:

assistant/
  AGENT.md
  runtime.json                   { "kind": "virtual" }, for the plugin's skill
  plugins/github/
    plugin.json                  $schema, name, version
    mcp.json                     the plugin's MCP servers
    skills/open-pr/SKILL.md
    hooks/hooks.json             kept with the source, not run
assistant/plugins/github/plugin.json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "github",
  "version": "1.2.0"
}

Copy the plugin in exactly as it was published: plugin.json and mcp.json name their Agent Plugins $schema. Its skills and its mcp.json servers join the agent's with the label { name: "github", version: "1.2.0" }. Unlike .plugin(), which skips an invalid part with a warning, the folder compiler refuses an invalid skill or server, as it refuses one of the agent's own. What Nylorun does not run, such as hooks and commands, is a note:

$ npx nylorun check assistant
assistant/plugins/github/hooks/ note: Hooks are not run by Nylorun
assistant: ok, agent manifest assistant (6 files, agent-folder/1)

In a harness file

Harness files are the deprecated three-file format. In one, plugins lists plugin folders, each folded in as .plugin() folds it, and mcpServers may be the path of an mcp.json in the Agent Plugins format:

harness.manifest.json
{
  "$schema": "https://docs.nylorun.com/schemas/harness-manifest/v1.2.json",
  "instructions": ["Use the plugin tools and skills."],
  "plugins": ["../../plugins/github"],
  "mcpServers": "./mcp.json"
}

npx nylorun migrate folder <dir> converts such a folder to AGENT.md and its files.

Loading and diagnostics

loadPlugin is the lower-level reader if you want the loaded package and its diagnostics before attaching it. .plugin() emits each warning as a NylorunPluginWarning process warning; diagnostics are never part of the manifest.

MCP servers inside a plugin use the same map shape as .mcp() and must be remote: streamable-http or sse. A plugin whose mcp.json declares a stdio server makes .plugin() throw PluginError (plugin.mcp-stdio). A remote server that does not validate, such as one whose key is not a valid name (letters, digits, _ and -, up to 64 characters), is left out with a plugin.mcp-server-skipped warning in the diagnostics, since the Runtime would refuse the manifest. The Runtime discovers the remote servers' tools on the first turn and pins them for the session.

Where a plugin shows

The label follows the plugin's parts into the session's record:

  • mcp.discovered names each server's plugin.
  • tool.completed and the rows of session.toolCalls() carry plugin for a call of a plugin's MCP server or skill. See Events.
  • Studio shows a plugin badge on each skill and server in a session's Manifest tab, with a filter by plugin, and on each tool call. See Studio.

Next step

On this page