{"meta":{"title":"GitHub Copilot CLI plugin reference","intro":"Find commands and configuration details for CLI plugins.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/copilot","title":"GitHub Copilot"},{"href":"/en/copilot/reference","title":"Reference"},{"href":"/en/copilot/reference/copilot-cli-reference","title":"Copilot CLI reference"},{"href":"/en/copilot/reference/copilot-cli-reference/cli-plugin-reference","title":"CLI plugin reference"}],"documentType":"article"},"body":"# GitHub Copilot CLI plugin reference\n\nFind commands and configuration details for CLI plugins.\n\n> \\[!NOTE]\n> You can find help on using plugins by entering `copilot plugin [SUBCOMMAND] --help` in the terminal.\n\n## CLI commands\n\nYou can use the following commands in the terminal to manage plugins for Copilot CLI.\n\n| Command | Description |\n| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |\n| `copilot plugin install SPECIFICATION` | Install a plugin. See [Plugin specification for `install` command](#plugin-specification-for-install-command) below. |\n| `copilot plugin uninstall NAME` | Remove a plugin |\n| `copilot plugin list` | List installed plugins |\n| `copilot plugin update NAME` | Update a plugin |\n| `copilot plugin marketplace add SPECIFICATION` | Register a marketplace |\n| `copilot plugin marketplace list` | List registered marketplaces |\n| `copilot plugin marketplace browse NAME` | Browse marketplace plugins |\n| `copilot plugin marketplace remove NAME` | Unregister a marketplace |\n\n### Plugin specification for `install` command\n\n| Format | Example | Description |\n| -------------- | ---------------------------- | ------------------------------------ |\n| Marketplace | `plugin@marketplace` | Plugin from a registered marketplace |\n| GitHub | `OWNER/REPO` | Root of a GitHub repository |\n| GitHub subdir | `OWNER/REPO:PATH/TO/PLUGIN` | Subdirectory in a repository |\n| Git URL | `https://github.com/o/r.git` | Any Git URL |\n| Local path | `./my-plugin` or `/abs/path` | Local directory |\n\n## `plugin.json`\n\nAll plugins consist of a plugin directory containing, at minimum, a manifest file named `plugin.json` located at the root of the plugin directory. See [Creating a plugin for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating).\n\n### Required field\n\n| Field | Type | Description |\n| ------ | ------ | ---------------------------------------------------------------------- |\n| `name` | string | Kebab-case plugin name (letters, numbers, hyphens only). Max 64 chars. |\n\n### Optional metadata fields\n\n| Field | Type | Description |\n| ------------- | --------- | -------------------------------------------------------- |\n| `description` | string | Brief description. Max 1024 chars. |\n| `version` | string | Semantic version (e.g., `1.0.0`). |\n| `author` | object | `name` (required), `email` (optional), `url` (optional). |\n| `homepage` | string | Plugin homepage URL. |\n| `repository` | string | Source repository URL. |\n| `license` | string | License identifier (e.g., `MIT`). |\n| `keywords` | string\\[] | Search keywords. |\n| `category` | string | Plugin category. |\n| `tags` | string\\[] | Additional tags. |\n\n### Component path fields\n\nThese tell the CLI where to find your plugin's components. All are optional. The CLI uses default conventions if omitted.\n\n| Field | Type | Default | Description |\n| ------------ | ------------------- | --------- | ----------------------------------------------------------------------------- |\n| `agents` | string \\| string\\[] | `agents/` | Path(s) to agent directories (`.agent.md` files). |\n| `skills` | string \\| string\\[] | `skills/` | Path(s) to skill directories (`SKILL.md` files). |\n| `commands` | string \\| string\\[] | — | Path(s) to command directories. |\n| `hooks` | string \\| object | — | Path to a hooks config file, or an inline hooks object. |\n| `mcpServers` | string \\| object | — | Path to an MCP config file (e.g., `.mcp.json`), or inline server definitions. |\n| `lspServers` | string \\| object | — | Path to an LSP config file, or inline server definitions. |\n\n### Example `plugin.json` file\n\n```json copy\n{\n \"name\": \"my-dev-tools\",\n \"description\": \"React development utilities\",\n \"version\": \"1.2.0\",\n \"author\": {\n \"name\": \"Jane Doe\",\n \"email\": \"jane@example.com\"\n },\n \"license\": \"MIT\",\n \"keywords\": [\"react\", \"frontend\"],\n \"agents\": \"agents/\",\n \"skills\": [\"skills/\", \"extra-skills/\"],\n \"hooks\": \"hooks.json\",\n \"mcpServers\": \".mcp.json\"\n}\n```\n\n## `marketplace.json`\n\nYou can create a plugin marketplace—which people can use to discover and install your plugins—by creating a `marketplace.json` file and saving it to the `.github/plugin/` directory of the repository. You can also store the `marketplace.json` file in your local file system. For example, saving the file as `/PATH/TO/my-marketplace/.github/plugin/marketplace.json` allows you to add it to the CLI using the following command:\n\n```shell\ncopilot plugin marketplace add /PATH/TO/my-marketplace\n```\n\n> \\[!NOTE]\n> Copilot CLI also looks for the `marketplace.json` file in the `.claude-plugin/` directory.\n\nFor more information, see [Creating a plugin marketplace for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-marketplace).\n\n### Example `marketplace.json` file\n\n```json copy\n{\n \"name\": \"my-marketplace\",\n \"owner\": {\n \"name\": \"Your Organization\",\n \"email\": \"plugins@example.com\"\n },\n \"metadata\": {\n \"description\": \"Curated plugins for our team\",\n \"version\": \"1.0.0\"\n },\n \"plugins\": [\n {\n \"name\": \"frontend-design\",\n \"description\": \"Create a professional-looking GUI ...\",\n \"version\": \"2.1.0\",\n \"source\": \"./plugins/frontend-design\"\n },\n {\n \"name\": \"security-checks\",\n \"description\": \"Check for potential security vulnerabilities ...\",\n \"version\": \"1.3.0\",\n \"source\": \"./plugins/security-checks\"\n }\n ]\n}\n```\n\n> \\[!NOTE]\n> The value of the `source` field for each plugin is the path to the plugin's directory, relative to the root of the repository. It is not necessary to use `./` at the start of the path. For example, `\"./plugins/plugin-name\"` and `\"plugins/plugin-name\"` resolve to the same directory.\n\n### `marketplace.json` fields\n\n#### Top-level fields\n\n| Field | Type | Required | Description |\n| ---------- | ------ | -------- | --------------------------------------------- |\n| `name` | string | Yes | Kebab-case marketplace name. Max 64 chars. |\n| `owner` | object | Yes | `{ name, email? }` — marketplace owner info. |\n| `plugins` | array | Yes | List of plugin entries (see the table below). |\n| `metadata` | object | No | `{ description?, version?, pluginRoot? }` |\n\n#### Plugin entry fields (objects within the `plugins` array)\n\n| Field | Type | Required | Description |\n| ------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name` | string | Yes | Kebab-case plugin name. Max 64 chars. |\n| `source` | string \\| object | Yes | Where to fetch the plugin (relative path, GitHub, or URL). |\n| `description` | string | No | Plugin description. Max 1024 chars. |\n| `version` | string | No | Plugin version. |\n| `author` | object | No | `{ name, email?, url? }` |\n| `homepage` | string | No | Plugin homepage URL. |\n| `repository` | string | No | Source repository URL. |\n| `license` | string | No | License identifier. |\n| `keywords` | string\\[] | No | Search keywords. |\n| `category` | string | No | Plugin category. |\n| `tags` | string\\[] | No | Additional tags. |\n| `commands` | string \\| string\\[] | No | Path(s) to command directories. |\n| `agents` | string \\| string\\[] | No | Path(s) to agent directories. |\n| `skills` | string \\| string\\[] | No | Path(s) to skill directories. |\n| `hooks` | string \\| object | No | Path to hooks config or inline hooks object. |\n| `mcpServers` | string \\| object | No | Path to MCP config or inline server definitions. |\n| `lspServers` | string \\| object | No | Path to LSP config or inline server definitions. |\n| `strict` | boolean | No | When `true` (the default), plugins must conform to the full schema and validation rules. When `false`, relaxed validation is used, allowing more flexibility—especially for direct installs or legacy plugins. |\n\n## File locations\n\n| Item | Path |\n| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Installed plugins | `~/.copilot/installed-plugins/MARKETPLACE/PLUGIN-NAME` (installed via a marketplace) and `~/.copilot/installed-plugins/_direct/SOURCE-ID/` (installed directly) |\n| Marketplace cache | Platform cache directory: `~/.cache/copilot/marketplaces/` (Linux), `~/Library/Caches/copilot/marketplaces/` (macOS). Overridable with `COPILOT_CACHE_HOME`. |\n| Plugin manifest | `.plugin/plugin.json`, `plugin.json`, `.github/plugin/plugin.json`, or `.claude-plugin/plugin.json` (checked in this order) |\n| Marketplace manifest | `marketplace.json`, `.plugin/marketplace.json`, `.github/plugin/marketplace.json`, or `.claude-plugin/marketplace.json` (checked in this order) |\n| Agents | `agents/` (default, overridable in manifest) |\n| Skills | `skills/` (default, overridable in manifest) |\n| Hooks configuration | `hooks.json` or `hooks/hooks.json` |\n| MCP configuration | `.mcp.json`, `.github/mcp.json` |\n| LSP configuration | `lsp.json` or `.github/lsp.json` |\n\n## Loading order and precedence\n\nIf you install multiple plugins it's possible that some custom agents, skills, MCP servers, or tools supplied via MCP servers have duplicate names. In this situation, the CLI determines which component to use based on a precedence order.\n\n* **Agents and skills** use first-found-wins precedence.\n\n If you have a project-level custom agent or skill with the same name or ID as one in a plugin you install, the agent or skill in the plugin is silently ignored. The plugin cannot override project-level or personal configurations. Custom agents are deduplicated using their ID, which is derived from its file name (for example, if the file is named `reviewer.agent.md`, the agent ID is `reviewer`). Skills are deduplicated by their name field inside the `SKILL.md` file.\n\n* **MCP servers** use last-wins precedence.\n\n If you install a plugin that defines an MCP server with the same server name as an MCP server you have already installed, the plugin's definition takes precedence. You can use the `--additional-mcp-config` command-line option to override an MCP server configuration with the same name, installed using a plugin.\n\n* **Built-in tools and agents** are always present and cannot be overridden by user-defined components.\n\nThe following diagram illustrates the loading order and precedence rules.\n\n```text\n┌──────────────────────────────────────────────────────────────────┐\n│ BUILT-IN - HARDCODED, ALWAYS PRESENT │\n│ • tools: bash, view, apply_patch, glob, rg, task, ... │\n│ • agents: explore, task, code-review, general-purpose, research │\n└────────────────────────┬─────────────────────────────────────────┘\n │\n ┌──────────────────────▼──────────────────────────────────────────────┐\n │ CUSTOM AGENTS - FIRST LOADED IS USED (dedup by ID) │\n │ 1. ~/.copilot/agents/ (user, .github convention) │\n │ 2. /.github/agents/ (project) │\n │ 3. /.github/agents/ (inherited, monorepo) │\n │ 4. ~/.claude/agents/ (user, .claude convention) │\n │ 5. /.claude/agents/ (project) │\n │ 6. /.claude/agents/ (inherited, monorepo) │\n │ 7. PLUGIN: agents/ dirs (plugin, by install order) │\n │ 8. Remote org/enterprise agents (remote, via API) │\n └──────────────────────┬──────────────────────────────────────────────┘\n │\n ┌──────────────────────▼──────────────────────────────────────────────┐\n │ AGENT SKILLS - FIRST LOADED IS USED (dedup by name) │\n │ 1. /.github/skills/ (project) │\n │ 2. /.agents/skills/ (project) │\n │ 3. /.claude/skills/ (project) │\n │ 4. /.github/skills/ etc. (inherited) │\n │ 5. ~/.copilot/skills/ (personal-copilot) │\n │ 6. ~/.agents/skills/ (personal-agents) │\n │ 7. ~/.claude/skills/ (personal-claude) │\n │ 8. PLUGIN: skills/ dirs (plugin) │\n │ 9. COPILOT_SKILLS_DIRS env + config (custom) │\n │ --- then commands (.claude/commands/), skills override commands ---│\n └──────────────────────┬──────────────────────────────────────────────┘\n │\n ┌──────────────────────▼──────────────────────────────────────────────┐\n │ MCP SERVERS - LAST LOADED IS USED (dedup by server name) │\n │ 1. ~/.copilot/mcp-config.json (lowest priority) │\n │ 2. PLUGIN: MCP configs (plugins) │\n │ 3. --additional-mcp-config flag (highest priority) │\n └─────────────────────────────────────────────────────────────────────┘\n```\n\n## Further reading\n\n* [GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli)\n* [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference)\n* [GitHub Copilot CLI programmatic reference](/en/copilot/reference/copilot-cli-reference/cli-programmatic-reference)"}