|
| 1 | +--- |
| 2 | +title: Creating a plugin for {% data variables.copilot.copilot_cli %} |
| 3 | +shortTitle: 'Plugins: Create a plugin' |
| 4 | +allowTitleToDifferFromFilename: true |
| 5 | +intro: 'Create a plugin to share customizations in an easy-to-install package.' |
| 6 | +versions: |
| 7 | + feature: copilot |
| 8 | +topics: |
| 9 | + - Copilot |
| 10 | +category: |
| 11 | + - Configure Copilot |
| 12 | + - Author and optimize with Copilot |
| 13 | +contentType: how-tos |
| 14 | +--- |
| 15 | + |
| 16 | +## Introduction |
| 17 | + |
| 18 | +Plugins are packages that extend the functionality of {% data variables.copilot.copilot_cli_short %}. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-cli-plugins). |
| 19 | + |
| 20 | +{% data reusables.copilot.cli-help-note %} |
| 21 | + |
| 22 | +## Plugin structure |
| 23 | + |
| 24 | +A plugin consists of a directory with a specific structure. At minimum, it must contain a `plugin.json` manifest file at the root of the directory. It can also contain any combination of agents, skills, hooks, and MCP server configurations. |
| 25 | + |
| 26 | +### Example plugin structure |
| 27 | + |
| 28 | +```text |
| 29 | +my-plugin/ |
| 30 | +├── plugin.json # Required manifest |
| 31 | +├── agents/ # Custom agents (optional) |
| 32 | +│ └── helper.agent.md |
| 33 | +├── skills/ # Skills (optional) |
| 34 | +│ └── deploy/ |
| 35 | +│ └── SKILL.md |
| 36 | +├── hooks.json # Hook configuration (optional) |
| 37 | +└── .mcp.json # MCP server config (optional) |
| 38 | +``` |
| 39 | + |
| 40 | +## Creating a plugin |
| 41 | + |
| 42 | +1. Create a directory for your plugin. |
| 43 | +1. Add a `plugin.json` manifest file to the root of the directory. |
| 44 | + |
| 45 | + **Example `plugin.json` file** |
| 46 | + |
| 47 | + {% data reusables.copilot.cli-example-plugin-file %} |
| 48 | + |
| 49 | + For details of the full set of fields you can include in this file, see [AUTOTITLE](/copilot/reference/cli-plugin-reference#pluginjson). |
| 50 | + |
| 51 | +1. Add some components to your plugin by creating the appropriate files and directories for agents, skills, hooks, and MCP server configurations. |
| 52 | + |
| 53 | + For example: |
| 54 | + |
| 55 | + 1. Add an agent by creating a `NAME.agent.md` file in an `agents` subdirectory. |
| 56 | + |
| 57 | + ```markdown copy |
| 58 | + --- |
| 59 | + name: my-agent |
| 60 | + description: Helps with specific tasks |
| 61 | + tools: ["bash", "edit", "view"] |
| 62 | + --- |
| 63 | + |
| 64 | + You are a specialized assistant that... |
| 65 | + ``` |
| 66 | + |
| 67 | + 1. 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. |
| 68 | + |
| 69 | + For example, to create a "deploy" skill, create `skills/deploy/SKILL.md`: |
| 70 | + |
| 71 | + ```markdown copy |
| 72 | + --- |
| 73 | + name: deploy |
| 74 | + description: Deploy the current project to... |
| 75 | + --- |
| 76 | + |
| 77 | + Instructions for the skill... |
| 78 | + ``` |
| 79 | + |
| 80 | +1. Install your plugin locally, so that you can test it as you develop it. |
| 81 | + |
| 82 | + For example, where `./my-plugin` is the path to your plugin directory, enter: |
| 83 | + |
| 84 | + ```shell copy |
| 85 | + copilot plugin install ./my-plugin |
| 86 | + ``` |
| 87 | + |
| 88 | +1. Verify that the plugin loaded successfully by viewing your list of installed plugins: |
| 89 | + |
| 90 | + ```shell copy |
| 91 | + copilot plugin list |
| 92 | + ``` |
| 93 | + |
| 94 | + Or you can start a new interactive session and enter: |
| 95 | + |
| 96 | + ```copilot copy |
| 97 | + /plugin list |
| 98 | + ``` |
| 99 | + |
| 100 | +1. Verify that the agents, skills, hooks, and MCP server configurations you defined are loaded correctly. |
| 101 | + |
| 102 | + For example, in an interactive session, to check that custom agents defined in the plugin were loaded, enter: |
| 103 | + |
| 104 | + ```copilot copy |
| 105 | + /agent |
| 106 | + ``` |
| 107 | + |
| 108 | + To check that skills defined in the plugin were loaded, enter: |
| 109 | + |
| 110 | + ```copilot copy |
| 111 | + /skills list |
| 112 | + ``` |
| 113 | + |
| 114 | +1. Use the functionality provided by your plugin's components to verify that each component works as expected. |
| 115 | +1. Iterate on your plugin development, as required. |
| 116 | + |
| 117 | + > [!IMPORTANT] |
| 118 | + > When you install a plugin its components are cached and the CLI reads from the cache for subsequent sessions. To pick up changes made to a local plugin install it again: |
| 119 | + > |
| 120 | + > ```shell copy |
| 121 | + > copilot plugin install ./my-plugin |
| 122 | + > ``` |
| 123 | +
|
| 124 | +1. After you have finished testing, you can uninstall the local version of your plugin by entering: |
| 125 | +
|
| 126 | + ```shell copy |
| 127 | + copilot plugin uninstall NAME |
| 128 | + ``` |
| 129 | +
|
| 130 | + > [!NOTE] |
| 131 | + > To uninstall a plugin, use the name of the plugin as specified in the `name` field of the plugin's `plugin.json` manifest file, not the path to the plugin's directory. |
| 132 | +
|
| 133 | +## Distributing your plugin |
| 134 | + |
| 135 | +To distribute your plugin, you can add it to a marketplace. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/plugins-marketplace). |
| 136 | + |
| 137 | +## Further reading |
| 138 | + |
| 139 | +* [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing) |
| 140 | +* [AUTOTITLE](/copilot/reference/cli-plugin-reference) |
0 commit comments