# Plugins (/docs/build/plugins)



Read an [Agent Plugin](https://agent-plugins.org/) package and attach it with
`.plugin(directory)`:

```ts
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()`](/docs/build/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.

```json
"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 [#as-a-folder]

In an [agent manifest](/docs/build/agent-manifests#plugins), a plugin vendored
under `plugins/<name>/` is folded in the same way:

```text
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
```

```json title="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:

```text
$ 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 [#in-a-harness-file]

Harness files are the deprecated
[three-file format](/docs/run/agent-manifests#three-files). 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:

```json title="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 [#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()`](/docs/build/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](/docs/build/agent#names) (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 [#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](/docs/run/events#tool-payloads).
* 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](/docs/run/studio#session).

## Next step [#next-step]

<Cards>
  <Card title="MCP" description="Declare MCP servers without a plugin package." href="/docs/build/mcp" />

  <Card title="Saving manifests" description="Save the agent with a runtime section." href="/docs/run/agent-manifests" />
</Cards>
