Practical guide · 10 minute read
How to Install Agent Plugins Safely
How to install Agent Plugins:first inspect the package and confirm that your client supports its format. Then install it from a reviewed repository, marketplace, or local path using that client's documented command, verify the loaded components, and remove it if anything is unexpected.
Before you install an Agent Plugin
Do not run an unreviewed third-party install script. A plugin may contain executable scripts or MCP commands and may connect to external services. Inspect the exact source and version first; never paste secrets into package files.
- A compatible client and a version that supports the package format.
- The repository URL, exact directory, tag, or commit you intend to install.
- Permission to install plugins under your account or organization policy.
- A disposable workspace for the first verification when possible.
Official standard, compatible packages, and client formats
Portable Agent Plugins 1.0
A root plugin.json points to the official 1.0 schema. Portable components live at skills/ and mcp.json. The standard does not define distribution or an install command.
Compatible client package
A client can recognize the portable manifest and add documented extensions. Confirm which portable components and transports that client actually loads.
Client-specific plugin
Formats such as .codex-plugin or .claude-plugin can add client-owned fields and locations. Install these only with that client’s documentation; compatibility is not implied.
How to Install Agent Plugins Step by Step
- 01
Confirm the package format and client support
Locate the manifest, identify whether it is a portable Agent Plugins 1.0 package or a client-specific bundle, and check that your client documents support for that format.
- 02
Inspect the source before installation
Review plugin.json, Skills, scripts, MCP commands, remote URLs, permissions, credentials, license, publisher, and recent repository changes.
- 03
Install with the client command
Use your client documentation. For GitHub Copilot CLI, install from a registered marketplace, GitHub repository, repository subdirectory, Git URL, or local directory.
Official GitHub Copilot CLI examples
copilot plugin install OWNER/REPOcopilot plugin install OWNER/REPO:PATH/TO/PLUGINcopilot plugin install PLUGIN-NAME@MARKETPLACE-NAMEcopilot plugin install ./reviewed-local-pluginThese are GitHub Copilot CLI commands, not universal Agent Plugins commands. Use copilot plugin --help and the current official documentation for your installed client version.
Verify the installation before trusting it
Confirm discovery
Run copilot plugin list in Copilot CLI, or use the equivalent plugin list in your client. Confirm the expected name, source, and enabled state.
Test least privilege
Start with a harmless, read-only task. Check which Skill activates and which MCP server or network request starts before approving credentials or write access.
Common installation errors
- Manifest not found
- Confirm the exact repository subdirectory and the manifest location supported by the client. A portable package uses plugin.json at its package root.
- Unsupported schema or component
- Update the client or select a package version it supports. A client may support Skills but not every MCP transport or extension.
- Plugin name collision
- List existing plugins and project-level components. Disable or rename the conflicting package only after checking precedence rules.
- MCP server fails to start
- Inspect the command, arguments, executable permissions, package-relative paths, and client-managed credentials. Do not weaken security controls to hide the error.
Update, disable, or uninstall an Agent Plugin
Review upstream changes before updating. Disable first when you are investigating behavior; uninstall when you no longer need the package. For GitHub Copilot CLI, use these documented commands:
copilot plugin update PLUGIN-NAMEcopilot plugin disable PLUGIN-NAMEcopilot plugin uninstall PLUGIN-NAMEUninstalling a plugin may not remove data or credentials kept in client-managed storage. Check the client documentation and revoke unused tokens separately.