v1.20Grok Build CLI support →

Plugins

A plugin is a single installable package that drops a team's custom skills, commands, hooks, and integrations into your agent in one step — like a VS Code extension, but for agents.

Why plugins exist

A skill solves one problem. A plugin packages a coherent set of skills, commands, hooks, and MCP servers under a single versioned manifest so a team can share tooling without coordinating which files go where. One agents plugins install call does it all, atomically.

Only Claude and OpenClaw support plugins today. A plugin can narrow this further by declaring agents: [...] in its manifest.

Install a plugin

# From a git URL
agents plugins install my-toolkit@https://github.com/user/my-toolkit.git

# From a local path
agents plugins install ~/Projects/my-plugin

Why some plugins need extra confirmation

Plugins that ship code that can run on its own — hooks, MCP servers, install scripts — ask for an explicit ok before they are allowed to execute. They install either way, but they will not fire until you say so. Pass --allow-exec-surfaces at install time, or flip the consent later in settings.json.


Plain plugin (skills + commands)       Plugin with hooks or MCP server
------------------------------------   ------------------------------------
agents plugins install my-toolkit      agents plugins install my-toolkit
           |                                      |
           v                                      v
  installs and runs immediately         installs but stays inactive
                                                  |
                                     add --allow-exec-surfaces
                                                  |
                                                  v
                                         hooks and MCP activate

This stops automated sync flows from silently activating third-party code that fires on every session event.

Manage plugins

agents plugins list                                  # table with sync status
agents plugins view my-plugin                        # metadata, resources, status
agents plugins sync my-plugin                        # re-apply after editing source
agents plugins update my-plugin                      # re-pull from git and re-sync
agents plugins remove my-plugin                      # unsync + delete source
agents plugins remove my-plugin --keep-source        # unsync only

Manifest

Every plugin needs a .claude-plugin/plugin.json at its root:

{
  "name": "git",
  "version": "1.0.0",
  "description": "Git workflow commands.",
  "agents": ["claude", "openclaw"]
}

The name field must match the directory name. Optional userConfig fields are prompted at install time and stored in .user-config.json. For actual credentials use a secrets bundle and reference it from a hook or skill.

Related