Creating a plugin for GitHub Copilot CLI

Create a plugin to share customizations in an easy-to-install package.

In this article

Plugins are packages that extend the functionality of Copilot CLI. For a cross-client overview, see Plugins for GitHub Copilot.

Note

You can find help on using plugins by entering copilot plugin [SUBCOMMAND] --help in the terminal.

Plugin structure

A plugin consists of a directory with a specific structure and a plugin.json manifest file. Agent Plugins 1.0 requires the manifest at the plugin root. Legacy plugins support additional manifest locations. A plugin can also contain any combination of agents, skills, hooks, and MCP server configurations.

Agent Plugins 1.0 is a portable format for skills and MCP servers across compatible clients. Copilot CLI also supports a legacy Copilot format.

  • To use Agent Plugins 1.0, declare the canonical $schema in plugin.json.
  • The legacy format supports Copilot-specific components and configurable component paths. In Copilot CLI, a manifest without the Agent Plugins $schema uses this format.

Choose Agent Plugins 1.0 when you want to share skills and MCP servers across compatible clients. Check the client documentation to confirm which other components it supports. Choose the legacy format when you need configurable component paths in Copilot CLI or are maintaining an existing Copilot-specific plugin.

Creating a plugin

  1. Create a directory for your plugin.

  2. Choose a plugin format, then add a plugin.json manifest file to the root of the directory.

    To create an Agent Plugins 1.0 plugin, include the canonical $schema:

    Example Agent Plugins 1.0 plugin.json file

    JSON
    {
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.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"]
}

    The schema allows only $schema, name, version, description, author, homepage, repository, license, keywords, and extensions as top-level fields. Copilot CLI reports and ignores unknown top-level fields. The extensions field is a map of client-specific data keyed by reverse-domain namespace.

    To create a legacy plugin, omit the Agent Plugins $schema. You can use component path fields in the manifest:

    Example legacy plugin.json file

    JSON
    {
  "name": "my-dev-tools",
  "description": "React development utilities",
  "agents": "agents/",
  "skills": ["skills/", "extra-skills/"],
  "hooks": "hooks.json",
  "mcpServers": ".mcp.json"
}

    For details of the full set of fields you can include in this file, see GitHub Copilot CLI plugin reference.

  3. Add components to your plugin.

    In an Agent Plugins 1.0 plugin, skills must be immediate subdirectories of skills/, and each skill must contain a SKILL.md file. MCP configuration must be in mcp.json at the plugin root. You cannot override these locations in plugin.json. Copilot-specific components go in the com.github.copilot directory, such as com.github.copilot/agents/ for custom agents and com.github.copilot/hooks/hooks.json for hooks.

    In a legacy plugin, use the default component locations or the component paths configured in plugin.json.

    For example:

    1. Add an agent by creating a NAME.agent.md file in an agents subdirectory. In an Agent Plugins 1.0 plugin, create the file in com.github.copilot/agents/. In a legacy plugin, create it in agents/.

      Markdown
      ---
name: my-agent
description: Helps with specific tasks
tools: ["bash", "edit", "view"]
---

You are a specialized assistant that...

    2. Add a skill by creating a skills/NAME subdirectory of your plugin directory, where NAME is the name of your skill. Then, within this subdirectory, create a SKILL.md file that defines the skill.

      For example, to create a "deploy" skill, create skills/deploy/SKILL.md:

      Markdown
      ---
name: deploy
description: Deploy the current project to...
---

Instructions for the skill...

    3. For an Agent Plugins 1.0 plugin, add MCP servers in a root mcp.json file. The MCP configuration uses its own Agent Plugins schema:

      JSON
      {
 "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
 "mcpServers": {
   "deployment-api": {
     "type": "streamable-http",
     "url": "https://deploy.example.com/mcp"
   },
   "local-validator": {
     "type": "stdio",
     "command": "node",
     "args": ["${PLUGIN_ROOT}/server/index.js"],
     "cwd": "${PLUGIN_ROOT}",
     "env": {
       "DATA_DIR": "${PLUGIN_DATA}/validator"
     }
   }
 }
}

      The streamable-http transport name is accepted for Streamable HTTP servers. For stdio servers, Copilot CLI provides PLUGIN_ROOT and PLUGIN_DATA environment variables and expands ${PLUGIN_ROOT} and ${PLUGIN_DATA} in args, env values, and cwd.

Test your plugin with GitHub Copilot CLI

The following commands test a plugin in Copilot CLI.

  1. Install your plugin locally, so that you can test it as you develop it.

    For example, where ./my-plugin is the path to your plugin directory, enter:

    Shell
    copilot plugin install ./my-plugin

  2. Verify that the plugin loaded successfully by viewing your list of installed plugins:

    Shell
    copilot plugin list

    Or you can start a new interactive session and enter:

    Copilot prompt
    /plugin list

  3. Verify that the agents, skills, hooks, and MCP server configurations you defined are loaded correctly.

    For example, in an interactive session, to check that custom agents defined in the plugin were loaded, enter:

    Copilot prompt
    /agent

    To check that skills defined in the plugin were loaded, enter:

    Copilot prompt
    /skills list

  4. Use the functionality provided by your plugin's components to verify that each component works as expected.

  5. Iterate on your plugin development, as required.

    Important

    When you install a plugin, its components are cached and Copilot CLI reads from the cache for subsequent sessions. To pick up changes made to a local plugin, install it again:

    Shell
    copilot plugin install ./my-plugin

  6. After you have finished testing, you can uninstall the local version of your plugin by entering:

    Shell
    copilot plugin uninstall NAME

    Use the value of the name field in the plugin's plugin.json manifest for NAME, not the path to the plugin directory.

Add evaluations for your plugin

Treat plugin context as agentic infrastructure. Add evaluations for the behaviors your plugin is meant to support, and run them when you change its instructions, tools, or other components.

Distribute your plugin

To share your plugin with others, add it to a marketplace. See Creating and sharing a plugin marketplace on GitHub.

Repository defaults can enable your plugin for a project. Members can override these defaults locally, but enterprise managed settings can require or block the plugin and always take precedence.

Further reading