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.

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:

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:

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