为 GitHub Copilot CLI 创建插件

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

在本文中

插件是用于扩展Copilot CLI功能的包。 有关跨客户端概述，请参阅 用于 GitHub Copilot 的插件。

注意

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

插件结构

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

Agent Plugins 1.0 是跨兼容客户端的技能和 MCP 服务器的可移植格式。 Copilot CLI 还支持旧 Copilot 格式。

  • 若要使用代理插件 1.0，请在 plugin.json 中声明规范 $schema。
  • 旧格式支持 Copilot特定组件和可配置组件路径。 在 Copilot CLI 中，不含 Agent Plugins $schema 的清单使用此格式。

如果要跨兼容客户端共享技能和 MCP 服务器，请选择 Agent Plugins 1.0。 检查客户端文档，确认它还支持哪些其他组件。 当您需要在 Copilot CLI 中使用可配置的组件路径，或正在维护现有的 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 作为顶级字段。 Copilot CLI 报告并忽略未知顶级字段。 该 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}。

使用 GitHub Copilot CLI 测试您的插件

以下命令在 Copilot CLI 中测试插件。

  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. 根据需要迭代您的插件开发。

    重要

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

    Shell
    copilot plugin install ./my-plugin

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

    Shell
    copilot plugin uninstall NAME

    使用插件的name``NAME清单中plugin.json字段的值，而不是插件目录的路径。

为插件添加评估

将插件上下文视为智能体基础设施。 添加插件旨在支持的行为评估，并在更改其说明、工具或其他组件时运行它们。

分发您的插件

若要与他人共享插件，请将其添加到市场。 请参阅“在 GitHub 上创建和共享插件市场”。

存储库默认值可以为项目启用您的插件。 成员可以在本地替代这些默认值，但企业托管设置可能要求或阻止该插件，并始终优先生效。

延伸阅读