为 GitHub Copilot CLI 创建插件

创建插件以在易于安装的包中共享自定义项。

在本文中

介绍

插件是用于扩展Copilot CLI功能的包。 请参阅“关于 GitHub Copilot 插件”。

注意

可以通过在终端中输入 copilot plugin [SUBCOMMAND] --help 来查找有关使用插件的帮助。

插件结构

插件由具有特定结构和 plugin.json 清单文件的目录组成。 Agent Plugins 1.0 要求清单文件位于插件根目录下。 旧版插件支持额外的清单位置。 插件还可以包含代理、技能、挂钩和 MCP 服务器配置的任意组合。

Copilot CLI 支持两种插件格式：

  • Agent 插件 1.0：一种适用于技能和 MCP 服务器的便携格式。 在 plugin.json 中声明规范项 $schema 会使该插件采用此格式。
  • 支持 Copilot 特定组件和可配置组件路径的旧版 Copilot 格式。 未包含 Agent 插件 $schema 的清单仍使用此格式。

支持这两种格式。 如果要使技能和 MCP 服务器可跨兼容客户端移植，请选择代理插件 1.0。 如果需要自定义组件路径或维护现有的 Copilot特定插件，请选择旧格式。 在代理插件 1.0 中，技能服务器和 MCP 服务器是可移植的， Copilot特定组件（如代理、命令、规则、挂钩和 LSP 服务器）来自 com.github.copilot 插件中的目录。

创建插件

  1. 为插件创建目录。

  2. 选择一种插件格式，然后将 plugin.json 清单文件添加到该目录的根目录。

    若要创建 Agent Plugins 1.0 插件，请包含规范形式的 $schema：

代理插件 1.0 plugin.json 文件示例

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"]
}

该架构描述仅允许 version、description、license、homepage、author、repository、keywords、extensions、name 和 $schema 作为顶级字段。 对于未知的顶级字段，会报告并忽略。 该 extensions 字段是由反向域命名空间键键的特定于客户端的数据的映射。

若要创建旧插件，请省略代理插件 $schema。 可以在清单中使用组件路径字段：

旧 plugin.json 文件示例

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

有关可包含在此文件中的完整字段集的详细信息，请参阅 GitHub Copilot CLI 插件参考。

  1. 将组件添加到插件。

    在 Agent Plugins 1.0 插件中，技能必须是 skills/ 的直接子目录，并且每个技能都必须包含一个 SKILL.md 文件。 MCP 配置必须位于 mcp.json 插件根目录中。 您不能在 plugin.json 中覆盖这些位置。 Copilot 特定组件放在 com.github.copilot 目录中，例如用于自定义代理的 com.github.copilot/agents/ 和用于钩子的 com.github.copilot/hooks/hooks.json。

    在旧插件中，使用默认组件位置或在其中 plugin.json配置的组件路径。

    例如：

    1. 通过在子目录中创建 NAME.agent.md 文件 agents 来添加代理。 在 Agent Plugins 1.0 插件中，在 com.github.copilot/agents/ 中创建该文件。 在旧版插件中，请在 agents/ 中创建它。

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

You are a specialized assistant that...

    2. 通过在插件目录中创建一个名为skills/NAME的子目录来添加技能，其中skills/NAME是技能的名称。 然后，在此子目录中，创建定义 SKILL.md 技能的文件。

      例如，若要创建“部署”技能，请创建 skills/deploy/SKILL.md：

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

Instructions for the skill...

    3. 对于代理插件 1.0 插件，请在根 mcp.json 文件中添加 MCP 服务器。 MCP 配置使用自己的代理插件架构：

      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"
     }
   }
 }
}

streamable-http 传输名称可用于可流式传输的 HTTP 服务器。 对于 stdio 服务器，Copilot CLI 提供 PLUGIN_ROOT 和 PLUGIN_DATA 环境变量，并在 args、env 值和 cwd 中展开 ${PLUGIN_ROOT} 和 ${PLUGIN_DATA}。

  1. 在本地安装插件，以便在开发插件时对其进行测试。

    例如，其中 ./my-plugin 是您的插件目录的路径，请输入：

    Shell
    copilot plugin install ./my-plugin

  2. 查看已安装的插件列表，验证插件是否已成功加载：

    Shell
    copilot plugin list

    或者，可以启动新的交互式会话并输入：

    Copilot prompt
    /plugin list

  3. 验证是否已正确加载定义的代理、技能、挂钩和 MCP 服务器配置。

    例如，在交互式会话中，若要检查插件中定义的自定义代理是否已加载，请输入：

    Copilot prompt
    /agent

    若要检查插件中定义的技能是否已加载，请输入：

    Copilot prompt
    /skills list

  4. 使用插件组件提供的功能来验证每个组件是否按预期工作。

  5. 根据需要迭代您的插件开发。

    重要

    安装插件时，会缓存其组件，CLI 会从缓存中读取后续会话。 若要使对本地插件的更改生效，请再次安装插件。

    Shell
    copilot plugin install ./my-plugin

  6. 测试完成后，可以通过输入以下内容卸载插件的本地版本：

    Shell
    copilot plugin uninstall NAME

    注意

    若要卸载插件，请使用插件清单文件字段中指定的 name 插件 plugin.json 名称，而不是插件目录的路径。

分发插件

若要分发插件，可以将其添加到市场。 请参阅“为 GitHub Copilot CLI 创建插件市场”。

延伸阅读