Plugins in Claude Agent SDK Deployments

## Overview

Plugins package Claude Code extensions (skills, agents, hooks, MCP servers) into
a shareable unit. The Claude Agent SDK can load plugins from local directories so
your agent sessions gain those capabilities programmatically.

## Load plugins

Provide local paths via the `plugins` option. The `type` must be `"local"` (the
only value the SDK accepts); for a marketplace plugin, download it first and pass
the local path.

```typescript
for await (const message of query({
  prompt: "Hello",
  options: {
    plugins: [
      { type: "local", path: "./my-plugin" },
      { type: "local", path: "/absolute/path/to/another-plugin" },
    ],
  },
})) { /* ... */ }
```

The path should point at the plugin root (the parent of `skills/`, `agents/`,
`hooks/`, or `.claude-plugin/`), not a subdirectory. Relative paths resolve from
the current working directory.

## Verify the load

When plugins load, they appear in the `system` `init` message. Check it (and its
`plugin_errors`) to confirm loads and fail CI on errors:

```typescript
if (message.type === "system" && message.subtype === "init") {
  console.log("Plugins:", message.plugins);          // [{ name, path }]
  console.log("Skills:", message.skills);            // ["my-plugin:greet"]
  console.log("Commands:", message.slash_commands);
}
```

## Invoke plugin skills

Plugin skills are namespaced with the plugin name to avoid conflicts. Invoke one
directly by sending `/plugin-name:skill-name` as the prompt:

```typescript
for await (const message of query({
  prompt: "/my-plugin:greet",
  options: { plugins: [{ type: "local", path: "./my-plugin" }] },
})) { /* ... */ }
```

CLI-installed plugins live under `~/.claude/plugins/`; point the SDK at that path
to reuse them.

## Common uses

- Load a plugin during development without installing it globally.
- Include project plugins in your repo for team-wide consistency.
- Combine plugins from multiple local locations in one session.

## Troubleshooting

- If a plugin does not appear, check the path points at the plugin root, validate
  any `plugin.json`, and confirm the directory is readable.
- If skills do not work, invoke them with the `/plugin-name:skill-name` namespace
  and confirm they appear in the init message's `skills` list.

## Source

- Plugins in the SDK: https://code.claude.com/docs/en/agent-sdk/plugins