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{
"$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:
{
"$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.discoverednames each server'splugin.tool.completedand the rows ofsession.toolCalls()carrypluginfor 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.