Defame1297
3e52636da6
## Why The initial research pass focused on agent definitions. An audit identified critical and minor gaps in both doc sets around plugin publishing, marketplace registration, and the Copilot extensibility model. ## Implementation Notes Claude Code gaps filled: end-to-end publish walkthrough (scaffold → validate → tag → host → register), CLI vs in-session command surface equivalence, all six marketplace source URL formats, plugin update/upgrade lifecycle, interactive plugin manager UI, private marketplace auth, `commands` vs `skills/` distinction. Copilot gaps filled: discovered that the GitHub App-based Copilot Extensions track was sunset November 2025. Created copilot-extensions.md as historical reference (deprecated, with MCP servers as the current replacement path). Documented the agent vs. skillset extension type distinction, OAuth install flow, and VS Code Chat Participants as the surviving @mention mechanism. overview.md updated with a "Which Track to Use" decision table covering all four active tracks plus the deprecated one. Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
6.3 KiB
topic, source_keys
| topic | source_keys | |||||||
|---|---|---|---|---|---|---|---|---|
| overview |
|
GitHub Copilot Agents and Plugins — Overview
GitHub Copilot exposes four active extension tracks plus one deprecated track. They share some vocabulary but differ in distribution model, runtime context, and target audience. Pick the right track before building — they are not interchangeable.
Which Track to Use
| Goal | Track |
|---|---|
| Add tools/data sources to Copilot Chat across all IDEs and GitHub.com | MCP server (via GitHub MCP Registry) |
| Build a custom @mention agent running inside VS Code | VS Code Chat Participant (VS Code extension API) |
| Package and distribute agents/skills/hooks for Copilot CLI | CLI Plugin System |
| Custom agents in the cloud agent or IDE agents pane | Cloud/IDE Custom Agents |
| GitHub App-based Copilot Extension | Deprecated — do not build (sunset Nov 2025) |
Four Active Extension Tracks
1. CLI Plugin System
Plugins are installable packages for the Copilot CLI (gh copilot / copilot binary). A plugin bundles agents, skills, hooks, MCP servers, and LSP servers into a single directory with a plugin.json manifest. Plugins are discovered through marketplaces — Git repositories containing a marketplace.json registry — and installed via copilot plugin install.
This is the primary extensibility model for the CLI. It mirrors what you can configure locally (.agent.md files, SKILL.md files, hooks.json, .mcp.json) but makes those artifacts versionable and distributable.
2. Cloud / IDE Custom Agents
Custom agents for the GitHub Copilot cloud agent and supported IDEs are .md files committed to a repository under .github/copilot/agents/ (or equivalent organization/enterprise paths). They carry YAML frontmatter specifying tool restrictions, model selection, and MCP server bindings, with the prompt body following.
These agents are scoped at three levels — enterprise > organization > repository — with lower levels overriding higher ones on name collision. The feature is in public preview for JetBrains IDEs, Eclipse, and Xcode as of the time of research.
3. SDK Custom Agents (Programmatic)
The Copilot SDK (@github/copilot-sdk for TypeScript, plus Go, Python, Java, .NET packages) lets application developers attach named CustomAgentConfig objects to a session at creation time. The runtime can auto-select sub-agents based on task context (infer: true, the default) or require explicit invocation. This track is for building Copilot-powered applications rather than personalizing the CLI.
4. VS Code Chat Participants
VS Code extensions that implement the Chat Participant API (vscode.chat.createChatParticipant()) appear as @mention agents inside the Copilot Chat panel in VS Code. This is the current supported path for building an @mention-based agent that runs locally inside VS Code:
- Implemented as a standard VS Code extension (
.vsix) — no server required - Distributed via the VS Code Marketplace (marketplace.visualstudio.com), not the GitHub Marketplace
- Declared in
package.jsonundercontributes.chatParticipants - Has access to the VS Code Language Model API to call Copilot's built-in models
- Users invoke with
@participant-namein the Copilot Chat panel
This track is distinct from the deprecated GitHub App-based Copilot Extensions (see below). It is not affected by the November 2025 sunset.
Deprecated Track: GitHub App-based Copilot Extensions
From public preview (2024) through general availability (February 2025) until sunset on November 10, 2025, GitHub supported a GitHub Marketplace track where third-party tools registered a GitHub App backed by an SSE/HTTP server. These appeared as @mention agents in Copilot Chat across VS Code, GitHub.com, Visual Studio, and JetBrains IDEs.
This track is fully deprecated. @mention invocations stopped working at the sunset date. The replacement is MCP servers.
Two sub-types existed:
- Agent extensions — implemented a full chat backend with SSE streaming; could call any LLM
- Skillset extensions — defined up to 5 discrete HTTP skill endpoints; Copilot handled all AI routing and response generation
See copilot-extensions.md for full architecture documentation, historical endpoint contracts, and migration guidance.
Component Primitives
The first three active tracks build on the same underlying primitives. The VS Code Chat Participant track uses separate VS Code APIs.
| Primitive | CLI | Cloud Agent | SDK | VS Code Chat Participant |
|---|---|---|---|---|
| Agents | .agent.md files |
.md files with frontmatter |
CustomAgentConfig in code |
createChatParticipant() |
| Skills | SKILL.md in named subdirs |
SKILL.md (cloud variant) |
skillDirectories + skills[] |
vscode.lm.registerTool() |
| Hooks | hooks.json |
Not supported | Not applicable | Not applicable |
| MCP servers | .mcp.json |
mcp-servers: frontmatter block |
mcpServers in SessionConfig |
VS Code MCP config |
| LSP servers | lsp-config/servers.json |
Not supported | Not applicable | Not applicable |
| Distribution | Marketplace repo | Git repo (.github/copilot/agents/) |
Application code | VS Code Marketplace |
Loading Hierarchy (CLI)
For agents and skills, the first-found instance wins when names collide:
- Project-level:
.github/agents/,.claude/agents/ - Personal:
~/.copilot/agents/,~/.copilot/skills/ - Plugin-provided components
- Remote org/enterprise agents (lowest priority)
For MCP servers the rule is reversed: last-wins. The --additional-mcp-config CLI flag takes highest priority.
Built-in agents (explore, code-review, general-purpose, research, task) and built-in tools (bash, view, edit, grep, glob) cannot be overridden.
Sub-Agent Architecture
All three tracks support the sub-agent pattern: a coordinating agent delegates subtasks to specialized agents with restricted tool sets and isolated context windows. In the CLI and SDK, agents can spawn sub-agents; the SDK additionally streams structured lifecycle events (subagent.started, subagent.completed, subagent.failed) so host applications can display an agent-activity tree.