GitHub Copilot CLI plugin reference

CLI commands

You can use the following commands in the terminal to manage plugins for Copilot-CLI.

Plugin specification for install command

plugin.json

All 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.

Required field

Optional metadata fields

Component path fields

These tell the CLI where to find your plugin's components. All are optional. The CLI uses default conventions if omitted.

Example plugin.json file

{
  "name": "my-dev-tools",
  "description": "React development utilities",
  "version": "1.2.0",
  "author": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "license": "MIT",
  "keywords": ["react", "frontend"],
  "agents": "agents/",
  "skills": ["skills/", "extra-skills/"],
  "hooks": "hooks.json",
  "mcpServers": ".mcp.json"
}

{
  "name": "my-dev-tools",
  "description": "React development utilities",
  "version": "1.2.0",
  "author": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "license": "MIT",
  "keywords": ["react", "frontend"],
  "agents": "agents/",
  "skills": ["skills/", "extra-skills/"],
  "hooks": "hooks.json",
  "mcpServers": ".mcp.json"
}

marketplace.json

You 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:

copilot plugin marketplace add /PATH/TO/my-marketplace

For more information, see Creating a plugin marketplace for GitHub Copilot-CLI.

Example marketplace.json file

{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Organization",
    "email": "plugins@example.com"
  },
  "metadata": {
    "description": "Curated plugins for our team",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "frontend-design",
      "description": "Create a professional-looking GUI ...",
      "version": "2.1.0",
      "source": "./plugins/frontend-design"
    },
    {
      "name": "security-checks",
      "description": "Check for potential security vulnerabilities ...",
      "version": "1.3.0",
      "source": "./plugins/security-checks"
    }
  ]
}

{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Organization",
    "email": "plugins@example.com"
  },
  "metadata": {
    "description": "Curated plugins for our team",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "frontend-design",
      "description": "Create a professional-looking GUI ...",
      "version": "2.1.0",
      "source": "./plugins/frontend-design"
    },
    {
      "name": "security-checks",
      "description": "Check for potential security vulnerabilities ...",
      "version": "1.3.0",
      "source": "./plugins/security-checks"
    }
  ]
}

marketplace.json fields

Top-level fields

Plugin entry fields (objects within the plugins array)

File locations

Loading order and precedence

If 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.

• Agents and skills use first-found-wins precedence.

  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.

• MCP servers use last-wins precedence.

  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.

• Built-in tools and agents are always present and cannot be overridden by user-defined components.

The following diagram illustrates the loading order and precedence rules.

┌─────────────────────────────────────────────────────────┐
│  BUILT-IN - HARDCODED, ALWAYS PRESENT                   │
│  • tools: bash, view, apply_patch, glob, rg, task, ...  │
│  • agents: explore, task, code-review, general-purpose  │
└────────────────────────┬────────────────────────────────┘
                         │
  ┌──────────────────────▼──────────────────────────────────────────────┐
  │  CUSTOM AGENTS - FIRST LOADED IS USED (dedup by ID)                 │
  │  1. ~/.copilot/agents/           (user, .github convention)         │
  │  2. <project>/.github/agents/    (project)                          │
  │  3. <parents>/.github/agents/    (inherited, monorepo)              │
  │  4. ~/.claude/agents/            (user, .claude convention)         │
  │  5. <project>/.claude/agents/    (project)                          │
  │  6. <parents>/.claude/agents/    (inherited, monorepo)              │
  │  7. PLUGIN: agents/ dirs         (plugin, by install order)         │
  │  8. Remote org/enterprise agents (remote, via API)                  │
  └──────────────────────┬──────────────────────────────────────────────┘
                         │
  ┌──────────────────────▼──────────────────────────────────────────────┐
  │  AGENT SKILLS - FIRST LOADED IS USED (dedup by name)                │
  │  1. <project>/.github/skills/        (project)                      │
  │  2. <project>/.agents/skills/        (project)                      │
  │  3. <project>/.claude/skills/        (project)                      │
  │  4. <parents>/.github/skills/ etc.   (inherited)                    │
  │  5. ~/.copilot/skills/               (personal-copilot)             │
  │  6. ~/.claude/skills/                (personal-claude)              │
  │  7. PLUGIN: skills/ dirs             (plugin)                       │
  │  8. COPILOT_SKILLS_DIRS env + config (custom)                       │
  │  --- then commands (.claude/commands/), skills override commands ---│
  └──────────────────────┬──────────────────────────────────────────────┘
                         │
  ┌──────────────────────▼──────────────────────────────────────────────┐
  │  MCP SERVERS - LAST LOADED IS USED (dedup by server name)           │
  │  1. ~/.copilot/mcp-config.json       (lowest priority)              │
  │  2. .vscode/mcp.json                 (workspace)                    │
  │  3. PLUGIN: MCP configs              (plugins)                      │
  │  4. --additional-mcp-config flag     (highest priority)             │
  └─────────────────────────────────────────────────────────────────────┘