docs(kyberforge): fill marketplace and plugin gaps in Claude Code and Copilot research docs
## 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>
This commit is contained in:
@@ -20,6 +20,7 @@ source_keys:
|
||||
| `license` | string | No | SPDX license identifier |
|
||||
| `keywords` | string[] | No | Search/discovery tags |
|
||||
| `skills` | string | No | Path to skills directory (default: `./skills/`) |
|
||||
| `commands` | string[] | No | Legacy: explicit list of `.md` command file paths (prefer `skills/`) |
|
||||
| `agents` | string[] | No | Explicit list of agent file paths |
|
||||
| `hooks` | string | No | Path to hooks.json |
|
||||
| `mcpServers` | string | No | Path to MCP server config |
|
||||
@@ -64,15 +65,42 @@ Fields marked **No** in the "Plugin subagent?" column are silently ignored when
|
||||
|
||||
Multiple `--plugin-dir` flags are supported for loading multiple plugins.
|
||||
|
||||
## CLI Commands (terminal)
|
||||
|
||||
Run these outside a session, from any terminal. These are the same operations as the in-session `/plugin` commands — use whichever surface is available.
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `claude plugin init <name>` | Scaffold a new plugin under `~/.claude/skills/<name>/` |
|
||||
| `claude plugin list [--enabled\|--disabled]` | List installed plugins with version, source, and enabled status |
|
||||
| `claude plugin validate [<path>]` | Validate a plugin dir or marketplace dir (`.`); `--strict` promotes warnings to errors |
|
||||
| `claude plugin marketplace add <source>` | Add a marketplace; accepts GitHub shorthand, git URL, remote JSON URL, or local path |
|
||||
| `claude plugin tag [--push] [--dry-run] [--force]` | Tag a plugin release as `{name}--v{version}` and optionally push to remote |
|
||||
|
||||
**`claude plugin marketplace add` source formats:**
|
||||
|
||||
| Format | Example | Notes |
|
||||
|---|---|---|
|
||||
| GitHub shorthand | `owner/repo` | GitHub only. Pin: `owner/repo@ref` |
|
||||
| HTTPS git URL | `https://gitlab.com/company/plugins.git` | Any git host. Pin: append `#ref` |
|
||||
| SSH git URL | `git@gitlab.com:company/plugins.git` | Any git host. Pin: append `#ref` |
|
||||
| Remote JSON URL | `https://example.com/marketplace.json` | Must point directly to a `marketplace.json` file |
|
||||
| Local directory | `./my-marketplace` | Directory containing `marketplace.json` |
|
||||
| Local JSON file | `./path/to/marketplace.json` | Direct path to `marketplace.json` |
|
||||
|
||||
## In-Session Commands
|
||||
|
||||
Run these inside a running Claude Code session. The `/plugin` subcommands are equivalent to the `claude plugin` CLI subcommands above.
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `/reload-plugins` | Pick up plugin file changes without restarting the session |
|
||||
| `/plugin install` | Install a plugin from a configured marketplace |
|
||||
| `/plugin marketplace add <source>` | Add a marketplace source |
|
||||
| `claude plugin init <name>` | Scaffold a new plugin under `~/.claude/skills/<name>/` |
|
||||
| `claude plugin validate` | Run the same lint checks the marketplace submission pipeline runs |
|
||||
| `/plugin` | Open the interactive plugin manager (Discover / Installed / Marketplaces / Errors tabs) |
|
||||
| `/plugin install <name>@<marketplace>` | Install a plugin from a configured marketplace |
|
||||
| `/plugin list [--enabled\|--disabled]` | List all installed plugins |
|
||||
| `/plugin update [<name>]` | Update one or all installed plugins |
|
||||
| `/plugin marketplace add <source>` | Add a marketplace source (same formats as CLI above) |
|
||||
| `/plugin validate [<path>]` | Validate plugin or marketplace directory |
|
||||
| `/agents` | Open the agent management UI (Running + Library tabs) |
|
||||
| `/fork <directive>` | Spawn a fork subagent inheriting full conversation history |
|
||||
| `@agent-<name>` | Invoke a specific subagent for one task |
|
||||
|
||||
@@ -51,6 +51,29 @@ The manifest lives at `.claude-plugin/plugin.json` in the plugin root directory.
|
||||
|
||||
All path values in the manifest are relative to the plugin root.
|
||||
|
||||
## `commands` vs `skills`
|
||||
|
||||
The manifest supports two fields that both register slash-command-style invocations, but they use different formats and have different capabilities:
|
||||
|
||||
| Feature | `skills` | `commands` |
|
||||
|---|---|---|
|
||||
| Format | `skills/<name>/SKILL.md` directory per skill | Single `.md` files listed as paths |
|
||||
| Invocation | `/plugin-name:skill-name` (namespaced) | `/command-name` (global, no namespace) |
|
||||
| Autonomous use by Claude | Yes — Claude can invoke without an explicit `/` command | No — only user-typed `/` triggers it |
|
||||
| Status | Recommended | Legacy |
|
||||
|
||||
The `commands` field is the **legacy** slash-command format. It accepts an array of paths to individual Markdown files:
|
||||
|
||||
```json
|
||||
"commands": ["./custom/commands/special.md"]
|
||||
```
|
||||
|
||||
Each file is a single command definition equivalent to a `.md` file in `.claude/commands/`. The command is invoked as `/filename` (without the extension).
|
||||
|
||||
The `skills` field is the recommended replacement. A skill directory (`skills/<name>/SKILL.md`) provides the same `/name` invocation plus autonomous invocation by Claude (Claude can call the skill proactively without the user typing a `/` command). Skills also support bundling supporting files alongside `SKILL.md`.
|
||||
|
||||
**Practical rule**: use `skills/` for new plugin content. The `commands` field exists for backward compatibility when porting legacy `.claude/commands/` files into a plugin. The CLI supports both formats.
|
||||
|
||||
## Plugin `settings.json`
|
||||
|
||||
A `settings.json` at the plugin root applies default settings when the plugin is enabled. Currently supports only two keys:
|
||||
|
||||
@@ -44,16 +44,50 @@ This creates the plugin structure and registers it as `my-tool@skills-dir` on th
|
||||
|
||||
## Installing from a Marketplace
|
||||
|
||||
After configuring a marketplace source:
|
||||
After configuring a marketplace source, install a plugin:
|
||||
|
||||
```
|
||||
/plugin install
|
||||
/plugin install my-plugin@marketplace-name
|
||||
```
|
||||
|
||||
To add the community marketplace:
|
||||
### Adding a marketplace source
|
||||
|
||||
Both CLI and in-session commands are equivalent:
|
||||
|
||||
```bash
|
||||
# CLI — run from any terminal
|
||||
claude plugin marketplace add <source>
|
||||
|
||||
# In-session — run inside a running Claude Code session
|
||||
/plugin marketplace add <source>
|
||||
```
|
||||
|
||||
Accepted `<source>` formats:
|
||||
|
||||
| Format | Example |
|
||||
|---|---|
|
||||
| GitHub shorthand | `owner/repo` (pin with `owner/repo@ref`) |
|
||||
| HTTPS git URL | `https://gitlab.com/company/plugins.git` (pin with `#ref`) |
|
||||
| SSH git URL | `git@gitlab.com:company/plugins.git` (pin with `#ref`) |
|
||||
| Remote JSON URL | `https://example.com/marketplace.json` |
|
||||
| Local directory | `./my-marketplace` |
|
||||
| Local JSON file | `./path/to/marketplace.json` |
|
||||
|
||||
The `owner/repo` shorthand is GitHub-only. For Gitea, GitLab, or self-hosted git, use a full HTTPS or SSH URL.
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# Add the official community marketplace
|
||||
claude plugin marketplace add anthropics/claude-plugins-community
|
||||
/plugin marketplace add anthropics/claude-plugins-community
|
||||
|
||||
# Add a private Git marketplace (any host)
|
||||
claude plugin marketplace add https://gitea.example.com/org/plugins.git
|
||||
/plugin marketplace add git@gitlab.com:company/plugins.git
|
||||
|
||||
# Add a local marketplace for testing
|
||||
/plugin marketplace add ./my-marketplace
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
@@ -29,9 +29,177 @@ Two submission paths:
|
||||
|
||||
Before submitting, run `claude plugin validate` locally — the review pipeline runs the same check. Check `marketplace.json` in the community catalog to confirm installability after approval.
|
||||
|
||||
## End-to-End Publish Walkthrough
|
||||
|
||||
Sequential path from a plugin directory to something installable by others:
|
||||
|
||||
**1. Scaffold (or bring your own directory)**
|
||||
|
||||
```bash
|
||||
claude plugin init my-plugin
|
||||
```
|
||||
|
||||
Creates `~/.claude/skills/my-plugin/` with a stub `plugin.json`. For a standalone plugin repo, create the directory structure manually.
|
||||
|
||||
**2. Write the manifest**
|
||||
|
||||
`plugin.json` (or `.claude-plugin/plugin.json`) at the plugin root:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"description": "What this plugin does",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
`name` is the only required field. Must be kebab-case with no spaces. Becomes the namespace prefix for all skills, agents, and hooks: `my-plugin:skill-name`.
|
||||
|
||||
**3. Validate the plugin**
|
||||
|
||||
```bash
|
||||
claude plugin validate ./my-plugin
|
||||
```
|
||||
|
||||
Checks `plugin.json` schema and type compliance, plus skills, agent, command, and hook files inside the directory. Use `--strict` to promote warnings (e.g. unrecognized fields) to errors — recommended in CI.
|
||||
|
||||
**4. Create the marketplace catalog**
|
||||
|
||||
In the repo that will serve as your marketplace, create `marketplace.json` at the root:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugins",
|
||||
"owner": { "name": "Your Name" },
|
||||
"plugins": [
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"source": "./plugins/my-plugin",
|
||||
"description": "What this plugin does",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**5. Validate the marketplace**
|
||||
|
||||
```bash
|
||||
# CLI
|
||||
claude plugin validate .
|
||||
|
||||
# In-session
|
||||
/plugin validate .
|
||||
```
|
||||
|
||||
Checks `marketplace.json` for: schema compliance, duplicate plugin names, source path traversal, version mismatches.
|
||||
|
||||
**6. Tag a release**
|
||||
|
||||
```bash
|
||||
claude plugin tag --push
|
||||
```
|
||||
|
||||
Creates a git tag in the format `{plugin-name}--v{version}` (e.g. `my-plugin--v1.0.0`), validates a clean working tree, and pushes to remote. Without `--push`, the tag is created locally only. Downstream plugins that declare a version constraint on this plugin resolve against these tags.
|
||||
|
||||
Preview without creating:
|
||||
|
||||
```bash
|
||||
claude plugin tag --dry-run
|
||||
```
|
||||
|
||||
**7. Host the repository**
|
||||
|
||||
Push to any git service — GitHub, GitLab, Gitea, Bitbucket, or a self-hosted server. The marketplace is the git repository containing `marketplace.json`. Alternatively, serve `marketplace.json` directly at an HTTPS URL.
|
||||
|
||||
**8. Register the marketplace with users**
|
||||
|
||||
Both surfaces accept the same source formats (see "Registering a private marketplace" below):
|
||||
|
||||
```bash
|
||||
# CLI (from any terminal)
|
||||
claude plugin marketplace add owner/repo
|
||||
|
||||
# In-session (inside a running Claude Code session)
|
||||
/plugin marketplace add owner/repo
|
||||
```
|
||||
|
||||
**9. Install from the marketplace**
|
||||
|
||||
Once registered:
|
||||
|
||||
```
|
||||
/plugin install my-plugin@my-plugins
|
||||
```
|
||||
|
||||
**10. Submit to the community marketplace (optional)**
|
||||
|
||||
See "Submitting to the Community Marketplace" above.
|
||||
|
||||
## Private / Team Marketplaces
|
||||
|
||||
Teams can host private marketplaces in private git repositories. The marketplace definition is a JSON file:
|
||||
Teams can host private marketplaces in any git repository. The marketplace definition is a JSON file at the repo root (or a specified subdirectory).
|
||||
|
||||
### Registering a private marketplace
|
||||
|
||||
Both CLI and in-session commands are equivalent — use whichever surface is available:
|
||||
|
||||
| Surface | Command |
|
||||
|---|---|
|
||||
| CLI (terminal) | `claude plugin marketplace add <source>` |
|
||||
| In-session | `/plugin marketplace add <source>` |
|
||||
|
||||
**Accepted `<source>` formats:**
|
||||
|
||||
| Format | Example | Notes |
|
||||
|---|---|---|
|
||||
| GitHub shorthand | `owner/repo` | GitHub only. Pin with `owner/repo@ref` |
|
||||
| HTTPS git URL | `https://gitlab.com/company/plugins.git` | Any git host. Pin with `#ref` suffix |
|
||||
| SSH git URL | `git@gitlab.com:company/plugins.git` | Any git host. Pin with `#ref` suffix |
|
||||
| Remote JSON URL | `https://example.com/marketplace.json` | Must point directly to a `marketplace.json` file |
|
||||
| Local directory | `./my-marketplace` | Directory containing `marketplace.json` |
|
||||
| Local JSON file | `./path/to/marketplace.json` | Direct path to the `marketplace.json` file |
|
||||
|
||||
Examples:
|
||||
|
||||
```shell
|
||||
# GitHub shorthand (GitHub only)
|
||||
claude plugin marketplace add acme-corp/claude-plugins
|
||||
|
||||
# HTTPS git URL (any host — GitHub, GitLab, Gitea, Bitbucket, self-hosted)
|
||||
/plugin marketplace add https://github.com/company/internal-plugins.git
|
||||
|
||||
# SSH
|
||||
/plugin marketplace add git@github.com:company/internal-plugins.git
|
||||
|
||||
# Pin to a branch, tag, or commit SHA
|
||||
/plugin marketplace add https://github.com/company/internal-plugins.git#v1.0.0
|
||||
claude plugin marketplace add owner/repo@main
|
||||
|
||||
# GitLab or Gitea work the same way with full URL
|
||||
/plugin marketplace add git@gitlab.com:company/plugins.git
|
||||
/plugin marketplace add https://gitea.example.com/org/plugins.git
|
||||
|
||||
# Local path for testing before hosting
|
||||
/plugin marketplace add ./my-marketplace
|
||||
/plugin marketplace add ./path/to/marketplace.json
|
||||
```
|
||||
|
||||
The `ref` (specified as `#ref` for git URLs or `@ref` for GitHub shorthand) can be a branch name, tag, or full commit SHA. Omitting it follows the default branch.
|
||||
|
||||
### Authentication for private repositories
|
||||
|
||||
**GitHub / GitHub Enterprise** — set the `GITHUB_TOKEN` environment variable. This is required for background auto-updates from private GitHub repositories:
|
||||
|
||||
```bash
|
||||
export GITHUB_TOKEN=ghp_... # personal access token or fine-grained PAT
|
||||
```
|
||||
|
||||
**SSH-based repos** — Claude Code uses the SSH keys configured in your local SSH agent. Ensure your key is loaded (`ssh-add`) before running Claude Code.
|
||||
|
||||
**Generic HTTPS with credentials** — configure credentials in your git credential store (e.g., `git credential-osxkeychain`, `git-credential-manager`, or `~/.netrc`). Claude Code delegates authentication to git for HTTPS clones.
|
||||
|
||||
### Marketplace JSON format
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -60,7 +228,125 @@ Teams can host private marketplaces in private git repositories. The marketplace
|
||||
}
|
||||
```
|
||||
|
||||
The `source` field accepts either a local path string or a `{ source: "github", repo: "org/repo" }` object.
|
||||
The `source` field accepts the following forms:
|
||||
|
||||
| Form | When to use |
|
||||
|---|---|
|
||||
| Local path string (`"./plugins/my-plugin"`) | Plugin lives in the same repo as the marketplace |
|
||||
| `{ "source": "github", "repo": "owner/repo" }` | Plugin lives in a separate GitHub repo; optionally add `"ref"` (branch/tag) and `"sha"` (exact commit; takes precedence over `ref`) |
|
||||
| `{ "source": "git", "url": "https://..." }` | Plugin in any git host via URL; optionally add `"ref"` for branch/tag |
|
||||
| `{ "source": "npm", "package": "@scope/pkg", "version": "1.0.0" }` | Plugin distributed on npm |
|
||||
|
||||
> **Note:** The `{ "source": "github", ... }` object form is documented only for GitHub. Gitea and GitLab repos are supported when registering the marketplace itself via `marketplace add`, but their behavior as an inline `source` value inside `marketplace.json` is unverified — use the `git` source type with a full URL instead, or confirm against official docs.
|
||||
|
||||
### Pre-registering via managed settings
|
||||
|
||||
For org-wide deployment, pre-register the marketplace in managed settings so it appears for all developers automatically:
|
||||
|
||||
```json
|
||||
{
|
||||
"extraKnownMarketplaces": {
|
||||
"internal-tools": {
|
||||
"source": {
|
||||
"source": "git",
|
||||
"url": "git@github.com:company/internal-plugins.git"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Settings-format source object for reference:
|
||||
|
||||
```json
|
||||
{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
|
||||
{ "source": "git", "url": "https://bitbucket.org/acme/plugins.git", "ref": "production" }
|
||||
{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }
|
||||
```
|
||||
|
||||
The `path` key scopes Claude Code to a subdirectory of the repo as the marketplace root.
|
||||
|
||||
## Plugin Discovery and Browsing
|
||||
|
||||
The primary browse interface is the interactive plugin manager, opened with `/plugin` (no arguments). It has four tabs:
|
||||
|
||||
| Tab | Purpose |
|
||||
|---|---|
|
||||
| **Discover** | Browse plugins from all registered marketplaces |
|
||||
| **Installed** | View and manage installed plugins |
|
||||
| **Marketplaces** | Add or remove marketplace sources |
|
||||
| **Errors** | Inspect plugin loading failures |
|
||||
|
||||
To list installed plugins non-interactively:
|
||||
|
||||
```shell
|
||||
/plugin list # all installed plugins (version, source, enabled status)
|
||||
/plugin list --enabled # only enabled plugins
|
||||
/plugin list --disabled # only disabled plugins
|
||||
```
|
||||
|
||||
CLI equivalent:
|
||||
|
||||
```bash
|
||||
claude plugin list [options]
|
||||
```
|
||||
|
||||
The `keywords` field in `plugin.json` feeds into the Discover tab's search index. Tags like `"git"`, `"formatting"`, or `"security"` make a plugin discoverable when users search those terms inside the plugin manager.
|
||||
|
||||
Administrators can allowlist specific marketplaces in managed settings; when set, Claude Code suggests relevant plugins for the current directory automatically.
|
||||
|
||||
## Plugin Update Lifecycle
|
||||
|
||||
### Manual update
|
||||
|
||||
```shell
|
||||
/plugin update # update all installed plugins
|
||||
/plugin update <name> # update a specific plugin
|
||||
```
|
||||
|
||||
After an update completes, Claude Code prompts you to run `/reload-plugins` to pick up changes in the current session.
|
||||
|
||||
### Auto-update at startup
|
||||
|
||||
Marketplaces and their installed plugins can be refreshed automatically each time Claude Code starts. When auto-update runs, marketplace catalogs are pulled and installed plugins are upgraded to their latest versions.
|
||||
|
||||
Control auto-update behavior with environment variables:
|
||||
|
||||
```bash
|
||||
export DISABLE_AUTOUPDATER=1 # prevent Claude Code itself from auto-updating
|
||||
export FORCE_AUTOUPDATE_PLUGINS=1 # force plugin auto-update even when DISABLE_AUTOUPDATER=1
|
||||
```
|
||||
|
||||
### Version resolution
|
||||
|
||||
Claude Code uses the installed version string as a cache key. On each update check it computes the current upstream version and skips the download if it matches the installed version.
|
||||
|
||||
For Git-based plugins: the version is derived from the git tag or commit SHA. If a plugin is pinned by a version constraint from another plugin, Claude Code automatically upgrades it to the highest satisfying tag.
|
||||
|
||||
### Version pinning
|
||||
|
||||
For npm-sourced plugins, pin to an exact version or range in the marketplace entry:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-npm-plugin",
|
||||
"source": {
|
||||
"source": "npm",
|
||||
"package": "@acme/claude-plugin",
|
||||
"version": "2.1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For Git-sourced plugins, pin to a branch, tag, or commit SHA via the `ref` field:
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "git",
|
||||
"url": "https://github.com/org/plugin.git",
|
||||
"ref": "v2.1.0"
|
||||
}
|
||||
```
|
||||
|
||||
## Loading Plugins
|
||||
|
||||
|
||||
@@ -3,14 +3,14 @@
|
||||
## context7-websites-code-claude
|
||||
|
||||
- **URL:** context7:/websites/code_claude
|
||||
- **Description:** Official Claude Code documentation site indexed by Context7 — plugin manifest schema, subagent definition types, marketplace JSON format, agent markdown file format
|
||||
- **Contributing files:** overview.md, agent-definition.md, configuration.md, examples.md, api-reference.md, marketplace.md
|
||||
- **Description:** Official Claude Code documentation site indexed by Context7 — plugin manifest schema, subagent definition types, marketplace JSON format, agent markdown file format, plugin update lifecycle, interactive plugin manager UI, private marketplace authentication, `commands` vs `skills/` distinction
|
||||
- **Contributing files:** overview.md, agent-definition.md, configuration.md, examples.md, api-reference.md, marketplace.md, installation.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## claude-code-plugins-docs
|
||||
|
||||
- **URL:** https://code.claude.com/docs/en/plugins
|
||||
- **Description:** Official Claude Code plugin authoring guide — plugin structure, manifest fields, loading methods, skill namespacing, agent activation, marketplace submission
|
||||
- **Description:** Official Claude Code plugin authoring guide — plugin structure, manifest fields, loading methods, skill namespacing, agent activation, marketplace submission, end-to-end publish walkthrough, `claude plugin validate` behavior, marketplace source URL formats, CLI vs in-session command equivalence
|
||||
- **Contributing files:** overview.md, installation.md, configuration.md, examples.md, api-reference.md, marketplace.md, troubleshooting.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
|
||||
@@ -0,0 +1,191 @@
|
||||
---
|
||||
topic: copilot-extensions
|
||||
source_keys:
|
||||
- github-changelog-copilot-extensions-ga
|
||||
- github-changelog-copilot-extensions-sunset
|
||||
- github-docs-copilot-extensions-skillsets
|
||||
- github-docs-copilot-extensions-building
|
||||
- vscode-chat-participant-api
|
||||
status: historical-with-current-successor
|
||||
---
|
||||
|
||||
# GitHub Copilot Extensions — GitHub App Track
|
||||
|
||||
> **DEPRECATION NOTICE**
|
||||
> GitHub App-based Copilot Extensions were generally available from February 2025 and **sunset on November 10, 2025** at 11:59 PM PST. New extensions could not be registered after September 24, 2025. All @mention invocations stopped working at the sunset date.
|
||||
>
|
||||
> **The replacement is MCP servers.** Any tool previously exposed as a Copilot Extension should now be published as an MCP server and added to the GitHub MCP Registry. See the [MCP section below](#replacement-mcp-servers) for the current path.
|
||||
>
|
||||
> **VS Code Chat Participants** (a separate VS Code extension API) are still supported and still provide @mention-based agents in VS Code. See the [VS Code Chat Participants section below](#vs-code-chat-participants-still-supported) for the surviving VS Code-specific mechanism.
|
||||
|
||||
This document covers the architecture of the now-deprecated GitHub App-based Copilot Extensions track for historical reference, plus the two surviving mechanisms that deliver the same @mention experience today.
|
||||
|
||||
---
|
||||
|
||||
## What GitHub App-based Copilot Extensions Were
|
||||
|
||||
GitHub App-based Copilot Extensions were a GitHub Marketplace distribution track where third parties (Sentry, DataStax, etc.) registered a **GitHub App** backed by a server and exposed it as a named @mention agent in Copilot Chat. Unlike the CLI plugin system (which installs into the `copilot` or `gh copilot` binary), these extensions surfaced inside Copilot Chat in:
|
||||
|
||||
- VS Code
|
||||
- GitHub.com web UI
|
||||
- Visual Studio
|
||||
- JetBrains IDEs
|
||||
|
||||
The key architectural difference from CLI plugins:
|
||||
|
||||
| Dimension | CLI Plugin System | GitHub App Extension (deprecated) |
|
||||
|---|---|---|
|
||||
| Distribution | `copilot plugin install` from a marketplace repo | Install from GitHub Marketplace as a GitHub App |
|
||||
| Runtime location | Inside the CLI binary on the developer's machine | External HTTP/SSE server operated by the extension publisher |
|
||||
| Access context | Terminal session, local files | Copilot Chat thread, optionally editor context |
|
||||
| Invocation | `@agent-name` in Copilot CLI interactive mode | `@extension-name` in Copilot Chat in IDE or GitHub.com |
|
||||
| Auth | n/a | OAuth / OIDC via GitHub |
|
||||
| Status | **Active** | **Deprecated (sunset Nov 10, 2025)** |
|
||||
|
||||
---
|
||||
|
||||
## Extension Types: Agent vs. Skillset
|
||||
|
||||
GitHub App-based Extensions had two sub-types. The choice was made at build time — one extension could not be both.
|
||||
|
||||
### Agent Extensions
|
||||
|
||||
Agent extensions implemented a full chat backend. The extension operated its own server, received conversation turns as POST requests, and streamed responses back via Server-Sent Events (SSE). The extension could:
|
||||
|
||||
- Call its own LLM or any third-party model
|
||||
- Integrate with the Copilot API to use Copilot's model
|
||||
- Manage conversation context across turns
|
||||
- Implement arbitrary business logic
|
||||
|
||||
Use agent extensions when: you need full control over how requests are processed, want to run your own model, or have complex multi-step workflows.
|
||||
|
||||
### Skillset Extensions
|
||||
|
||||
Skillset extensions defined up to **5 discrete API endpoints** (skills) that Copilot called when relevant. Copilot handled:
|
||||
|
||||
- Routing the user's message to the correct skill
|
||||
- Prompt crafting
|
||||
- Function evaluation
|
||||
- Response generation
|
||||
|
||||
The extension only needed to implement the skill endpoints themselves — no AI expertise required. Each skill was a simple HTTP endpoint that received structured input and returned structured output.
|
||||
|
||||
Use skillset extensions when: you need data retrieval or specific operations integrated into Copilot Chat with minimal setup.
|
||||
|
||||
An existing agent extension could be converted to a skillset, but not simultaneously operated as both types.
|
||||
|
||||
---
|
||||
|
||||
## Architecture (Historical Reference)
|
||||
|
||||
### GitHub App Registration
|
||||
|
||||
A Copilot Extension was always backed by a GitHub App. Required configuration:
|
||||
|
||||
1. **Homepage URL** — the extension's public-facing URL
|
||||
2. **Callback URL** — the OAuth callback endpoint on your server
|
||||
3. **GitHub Copilot Chat permission** — set to `Read-only`
|
||||
4. **Copilot Editor Context permission** — set to `Read-only` (enables passing current file context to the extension)
|
||||
5. **Webhooks** — typically disabled for extensions (the interaction model is request/response, not webhook push)
|
||||
|
||||
After registering the GitHub App, you configured it as a Copilot Extension by pointing to your backend server's hostname and specifying whether it was an agent or a skillset.
|
||||
|
||||
> **Note:** The exact registration fields and permission names should be confirmed against official docs if you are auditing historical extensions. The product was actively changing up to its sunset.
|
||||
|
||||
### SSE Endpoint Contract (Agent Extensions)
|
||||
|
||||
Agent extensions received `POST` requests with the user's message and context, and returned responses as a stream of Server-Sent Events. The general contract:
|
||||
|
||||
- **Request**: JSON body containing the conversation turn (user message, optional editor context, optional references). The `X-Github-Token` header (or OIDC token after GA) identified the user.
|
||||
- **Response**: `text/event-stream` with SSE events. Each event contained a chunk of the assistant's reply. A terminal event signalled end-of-stream.
|
||||
|
||||
> **Note:** The exact request/response schema for SSE events is unverified — confirm against official docs or archived documentation. The `copilot-extensions` GitHub org (`github.com/copilot-extensions`) had example implementations before sunset.
|
||||
|
||||
### Skillset Skill Endpoint Contract
|
||||
|
||||
Each skill was a `POST` endpoint that:
|
||||
- Received a structured JSON payload with the extracted parameters Copilot inferred from the user's message
|
||||
- Returned a JSON response with the result
|
||||
|
||||
Copilot assembled the final chat response from the skill's output without the skill needing to produce prose.
|
||||
|
||||
> **Note:** Unverified — confirm exact payload shape against archived official docs or `copilot-extensions/skillset-example` on GitHub.
|
||||
|
||||
### Authentication
|
||||
|
||||
At general availability (February 2025), GitHub replaced the original `X-Github-Token` auth header model with **OIDC support**, enabling direct third-party token authentication. This improved security by letting extensions validate tokens without proxying through GitHub.
|
||||
|
||||
---
|
||||
|
||||
## Publishing to GitHub Marketplace (Historical)
|
||||
|
||||
Publishing a GitHub App-based Copilot Extension required:
|
||||
|
||||
1. **Verified publisher**: the publishing GitHub App must belong to an organization that is a verified publisher on the GitHub Marketplace.
|
||||
2. **Organization owner role**: app managers without owner status could not publish.
|
||||
3. **Capability description**: the extension must respond meaningfully to "What can you do?" or "List your capabilities."
|
||||
4. **Stable UX**: the extension must deliver the features described in its Marketplace listing.
|
||||
5. **Low-friction onboarding**: new users must be able to install, set up, and authorize the extension with minimal steps.
|
||||
6. **Draft listing → Submit for review**: after completing the Marketplace listing form, you clicked "Submit for review." GitHub's team reviewed for quality, performance, reliability, and security. Denials included reasons; extensions could be revised and resubmitted.
|
||||
|
||||
> **Note:** Paid plans were not approved during the public preview period. Marketplace listing requirements are documented at `docs.github.com/en/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app`.
|
||||
|
||||
---
|
||||
|
||||
## End-User Install Flow (Historical)
|
||||
|
||||
1. **Discover**: user visited GitHub Marketplace (`github.com/marketplace?type=apps&copilot_app=true`) and found an extension.
|
||||
2. **Install**: clicked the "Install" button on the extension's Marketplace listing, which initiated a GitHub App installation — the standard GitHub OAuth/permissions consent screen, granting the app the scopes it requested.
|
||||
3. **Authorize**: on first use, some extensions required an additional OAuth authorization step to link the user's account with the extension's backend service.
|
||||
4. **Verify activation**: after install, the extension appeared as an available @mention in Copilot Chat. Users could verify by typing `@` in the Copilot Chat panel in VS Code or on GitHub.com.
|
||||
5. **Invoke**: type `@extension-name` followed by a natural language request. The extension handled the turn and streamed its response.
|
||||
|
||||
Organization admins could restrict which extensions were installable by members via the organization's Copilot settings.
|
||||
|
||||
---
|
||||
|
||||
## Replacement: MCP Servers
|
||||
|
||||
GitHub recommended MCP servers as the architectural replacement for GitHub App-based Copilot Extensions. The rationale: MCP is a universal standard — build the server once and it works across any compatible AI agent or chatbot, not only GitHub Copilot.
|
||||
|
||||
Key differences:
|
||||
|
||||
| Dimension | GitHub App Extension (deprecated) | MCP Server |
|
||||
|---|---|---|
|
||||
| Standard | GitHub-proprietary | Open (Anthropic / industry-wide) |
|
||||
| Scope | GitHub Copilot only | Any MCP-compatible AI agent |
|
||||
| Distribution | GitHub Marketplace | GitHub MCP Registry (public preview) |
|
||||
| Integration in CLI | Not supported | `.mcp.json` config / `copilot plugin marketplace` |
|
||||
| Integration in VS Code | Native via GitHub App install | VS Code MCP panel or `@mcp` in extensions search |
|
||||
|
||||
To add an MCP server to GitHub Copilot in VS Code: open the MCP panel in Copilot Chat, browse the GitHub MCP Registry, and click Install. For CLI use: `copilot plugin marketplace add` with an MCP-capable marketplace, or configure directly in `.mcp.json`.
|
||||
|
||||
---
|
||||
|
||||
## VS Code Chat Participants — Still Supported
|
||||
|
||||
VS Code Copilot Extensions built with the VS Code Chat Participant API are **not** affected by the GitHub App sunset. This is a separate mechanism:
|
||||
|
||||
- Implemented as a standard VS Code extension (`.vsix`) that registers a chat participant via `vscode.chat.createChatParticipant()`
|
||||
- Distributed through the VS Code Marketplace, not the GitHub Marketplace
|
||||
- Invoked with `@participant-name` in the Copilot Chat panel inside VS Code
|
||||
- Defined in `package.json` under `contributes.chatParticipants`
|
||||
- Has access to VS Code Language Model API and can call Copilot's built-in models
|
||||
|
||||
This is the current supported path for building an @mention-based agent that lives inside VS Code. It does not require a GitHub App or any server-side component — the extension runs inside VS Code.
|
||||
|
||||
For publishing: submit to the VS Code Marketplace (marketplace.visualstudio.com) via the standard `vsce publish` flow. This is distinct from the GitHub Marketplace.
|
||||
|
||||
> **Note:** VS Code Chat Participant API documentation is at `code.visualstudio.com/api/extension-guides/ai/chat`.
|
||||
|
||||
---
|
||||
|
||||
## Choosing the Right Track in 2026
|
||||
|
||||
| Goal | Recommended track |
|
||||
|---|---|
|
||||
| Add tools/data sources to Copilot Chat (any IDE/GitHub.com) | MCP server registered in GitHub MCP Registry |
|
||||
| Build a custom @mention agent that runs inside VS Code | VS Code Chat Participant (vscode extension API) |
|
||||
| Package and distribute agents/skills/hooks for Copilot CLI | CLI Plugin System (`plugin.json` + marketplace) |
|
||||
| Custom agents in the Copilot cloud agent or IDE agents pane | Cloud/IDE Custom Agents (`.github/copilot/agents/` .md files) |
|
||||
| GitHub App-based Copilot Extension (deprecated) | Do not build — sunset November 10, 2025 |
|
||||
@@ -131,3 +131,34 @@ Reference implementations: `github/copilot-plugins` and `github/awesome-copilot`
|
||||
## The `strict` Field
|
||||
|
||||
When `strict: false` is set on a plugin entry, the CLI performs relaxed schema validation for that plugin. This is useful for plugins distributed as `.claude-plugin/` directories that also need to serve Claude Code — it allows extra or non-standard fields without failing validation.
|
||||
|
||||
---
|
||||
|
||||
## Contributing to the Official Registries
|
||||
|
||||
Two registries are active: `github/awesome-copilot` (community-driven) and `github/copilot-plugins` (official GitHub collection). Both accept contributions via pull request.
|
||||
|
||||
### Submitting to `github/awesome-copilot`
|
||||
|
||||
`awesome-copilot` is a community-curated collection of agents, skills, instructions, hooks, workflows, and plugins. The repo is at `github.com/github/awesome-copilot`.
|
||||
|
||||
Contribution process:
|
||||
1. Fork `github/awesome-copilot`.
|
||||
2. Add your content in the appropriate directory (`agents/`, `skills/`, `plugins/`, etc.).
|
||||
3. Follow the formatting conventions in existing entries — `README.md` files in each directory describe the expected structure.
|
||||
4. Open a pull request against the `main` branch.
|
||||
5. Once the PR is merged, your content appears on `awesome-copilot.github.com`.
|
||||
|
||||
The repository's `CONTRIBUTING.md` (if present) is the authoritative guide for content requirements and review criteria.
|
||||
|
||||
### Submitting to `github/copilot-plugins`
|
||||
|
||||
`copilot-plugins` is the official GitHub Copilot plugins collection — it focuses on MCP servers, skills, hooks, and other CLI-extensibility tools.
|
||||
|
||||
Contribution process:
|
||||
1. Fork `github/copilot-plugins`.
|
||||
2. Add your plugin directory under `plugins/` following the `plugin.json` structure documented in this repo.
|
||||
3. Update `marketplace.json` (at `.github/plugin/marketplace.json`) to add an entry referencing your plugin.
|
||||
4. Open a pull request. The repo's contributing guide describes any additional requirements.
|
||||
|
||||
> **Note:** Specific review criteria and timelines for both registries are not authoritatively documented in public sources as of this research. Check each repo's `CONTRIBUTING.md` and open issues for current curator expectations before submitting.
|
||||
|
||||
@@ -6,13 +6,27 @@ source_keys:
|
||||
- github-cli-plugin-reference
|
||||
- github-custom-agents-configuration
|
||||
- github-sdk-custom-agents
|
||||
- github-changelog-copilot-extensions-sunset
|
||||
- vscode-chat-participant-api
|
||||
---
|
||||
|
||||
# GitHub Copilot Agents and Plugins — Overview
|
||||
|
||||
GitHub Copilot exposes three distinct extension tracks. They share some vocabulary but differ in distribution model, runtime context, and target audience.
|
||||
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.
|
||||
|
||||
## Three Extension Tracks
|
||||
## 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
|
||||
|
||||
@@ -30,17 +44,46 @@ These agents are scoped at three levels — **enterprise > organization > reposi
|
||||
|
||||
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.json` under `contributes.chatParticipants`
|
||||
- Has access to the VS Code Language Model API to call Copilot's built-in models
|
||||
- Users invoke with `@participant-name` in 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
|
||||
|
||||
All three tracks build on the same underlying 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 |
|
||||
|---|---|---|---|
|
||||
| Agents | `.agent.md` files | `.md` files with frontmatter | `CustomAgentConfig` in code |
|
||||
| Skills | `SKILL.md` in named subdirs | `SKILL.md` (cloud variant) | `skillDirectories` + `skills[]` |
|
||||
| Hooks | `hooks.json` | Not supported | Not applicable |
|
||||
| MCP servers | `.mcp.json` | `mcp-servers:` frontmatter block | `mcpServers` in `SessionConfig` |
|
||||
| LSP servers | `lsp-config/servers.json` | Not supported | Not applicable |
|
||||
| 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)
|
||||
|
||||
|
||||
@@ -48,3 +48,52 @@
|
||||
- **Description:** SDK custom agent API — CustomAgentConfig fields in all five languages, session config, sub-agent lifecycle events, tool scoping, permission handling
|
||||
- **Contributing files:** overview.md, agent-definition.md, api-reference.md, examples.md, sdk.md, troubleshooting.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## github-changelog-copilot-extensions-ga
|
||||
|
||||
- **URL:** https://github.blog/changelog/2025-02-19-announcing-the-general-availability-of-github-copilot-extensions/
|
||||
- **Description:** Announcement of GitHub Copilot Extensions general availability (February 2025) — OIDC auth, all license tiers, VS Code/Visual Studio/JetBrains/GitHub.com support
|
||||
- **Contributing files:** copilot-extensions.md
|
||||
- **Status:** `referenced`
|
||||
|
||||
## github-changelog-copilot-extensions-sunset
|
||||
|
||||
- **URL:** https://github.blog/changelog/2025-09-24-deprecate-github-copilot-extensions-github-apps/
|
||||
- **Description:** Sunset notice for GitHub App-based Copilot Extensions — creation blocked Sep 24, 2025; full shutdown Nov 10, 2025; MCP servers recommended as replacement
|
||||
- **Contributing files:** copilot-extensions.md, overview.md
|
||||
- **Status:** `referenced`
|
||||
|
||||
## github-docs-copilot-extensions-skillsets
|
||||
|
||||
- **URL:** https://docs.github.com/en/copilot/concepts/build-copilot-extensions/skillsets-for-copilot-extensions
|
||||
- **Description:** Concept doc for Copilot Extension skillsets — up to 5 skills per extension, Copilot handles routing/prompt crafting/response, contrast with agent extensions
|
||||
- **Contributing files:** copilot-extensions.md
|
||||
- **Status:** `referenced`
|
||||
|
||||
## github-docs-copilot-extensions-building
|
||||
|
||||
- **URL:** https://docs.github.com/en/copilot/building-copilot-extensions/setting-up-copilot-extensions
|
||||
- **Description:** How-to for setting up a Copilot Extension — GitHub App registration, Copilot Chat permission, Copilot Editor Context permission, backend URL configuration
|
||||
- **Contributing files:** copilot-extensions.md
|
||||
- **Status:** `referenced`
|
||||
|
||||
## vscode-chat-participant-api
|
||||
|
||||
- **URL:** https://code.visualstudio.com/api/extension-guides/ai/chat
|
||||
- **Description:** VS Code Chat Participant API — createChatParticipant(), package.json contributes.chatParticipants, Language Model API, @mention invocation in Copilot Chat
|
||||
- **Contributing files:** copilot-extensions.md, overview.md
|
||||
- **Status:** `referenced`
|
||||
|
||||
## github-marketplace-copilot-extensions
|
||||
|
||||
- **URL:** https://github.com/marketplace?type=apps&copilot_app=true
|
||||
- **Description:** GitHub Marketplace listing for Copilot Extensions — browsable list of available extensions (historical; page remains live but product is sunset)
|
||||
- **Contributing files:** copilot-extensions.md
|
||||
- **Status:** `referenced`
|
||||
|
||||
## github-docs-marketplace-listing-requirements
|
||||
|
||||
- **URL:** https://docs.github.com/en/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app
|
||||
- **Description:** Requirements for listing a GitHub App on the GitHub Marketplace — verified publisher, capability description, UX stability, submission and review process
|
||||
- **Contributing files:** copilot-extensions.md
|
||||
- **Status:** `referenced`
|
||||
|
||||
Reference in New Issue
Block a user