Defame1297
83e1a50a51
## Why Parallel research track to the Claude Code plugins research already committed. Needed to understand GitHub Copilot's extensibility model before designing cross-tool plugin compatibility for the kyberforge plugin system. ## Implementation Notes Three distinct Copilot extension tracks are covered: CLI plugins (plugin.json + marketplaces), cloud/IDE custom agents (frontmatter .md files committed to repos), and the SDK programmatic API. The SDK track got its own topic file (sdk.md) because the content doesn't fit neatly into the default topic list. Sources include Context7 (/websites/github_en_copilot), both user-provided reference URLs, and four additional deepened pages. ## Impact Provides a reference baseline for evaluating .claude-plugin/ / plugin.json compatibility between Claude Code and Copilot CLI — the two formats share a manifest discovery path and the strict:false field enables cross-tool plugin distribution. --- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
4.5 KiB
topic, source_keys
| topic | source_keys | |||||
|---|---|---|---|---|---|---|
| agent-definition |
|
Agent Definition Format
There are two file-based agent formats (CLI and cloud/IDE) and one programmatic format (SDK). They share vocabulary but differ in supported fields and runtime behavior.
CLI Agents (.agent.md files)
Stored in agents/ within a plugin directory, or directly in .github/agents/, .claude/agents/, or ~/.copilot/agents/. File extension must be .agent.md.
---
name: my-agent
description: Helps with specific tasks
tools: ["bash", "edit", "view"]
---
You are a specialized assistant that...
| Field | Required | Notes |
|---|---|---|
name |
Yes | Identifier; home-directory version wins over repo-level on collision |
description |
Yes | Used by the runtime for automatic agent selection — quality matters |
tools |
No | Array of tool names; omit = all available tools |
Agents can be invoked with /AGENT-NAME in interactive sessions or --agent AGENT-NAME on the CLI.
Cloud / IDE Custom Agents
Committed to .github/copilot/agents/ (repo), org-level, or enterprise-level paths as plain .md files. Scoping hierarchy: enterprise overrides are lowest priority; repo-level overrides are highest. Currently in public preview for JetBrains, Eclipse, and Xcode.
---
name: implementation-planner
description: Creates detailed implementation plans without executing code
target: github-copilot
tools: ["read", "search", "edit"]
model: claude-sonnet-4-5
---
You are a technical planning specialist...
| Field | Required | Default | Notes |
|---|---|---|---|
name |
No | — | Display name |
description |
Yes | — | Purpose and capabilities; drives auto-selection |
target |
No | both |
vscode or github-copilot; scopes which runtime loads this file |
tools |
No | all tools | Omit = all; [] = none; list = restrict to named tools |
model |
No | default model | Model to run this agent on |
disable-model-invocation |
No | false |
Prevents runtime from auto-selecting this agent |
user-invocable |
No | true |
Whether users can manually invoke this agent |
mcp-servers |
No | — | Extra MCP servers (cloud agent only; ignored in VS Code and most IDEs) |
metadata |
No | — | Key-value annotation pairs (ignored in VS Code) |
The infer field is retired — use disable-model-invocation + user-invocable instead.
Prompt body limit is 30,000 characters; content beyond this is truncated.
Tool Aliases
The following aliases are interchangeable in the tools field:
| Canonical Name | Accepted Aliases | Purpose |
|---|---|---|
execute |
shell, Bash, powershell |
Run shell commands |
read |
Read, NotebookRead |
Read file contents |
edit |
Edit, MultiEdit, Write, NotebookEdit |
Modify files |
search |
Grep, Glob |
Search files and text |
agent |
custom-agent, Task |
Invoke sub-agents |
web |
WebSearch, WebFetch |
Fetch URLs and web search |
todo |
TodoWrite |
Task lists (VS Code only) |
For MCP server tools, use server-name/tool-name syntax or server-name/* for all tools from a server.
MCP Server Declaration (cloud agent frontmatter)
mcp-servers:
custom-mcp:
type: 'local'
command: 'some-command'
args: ['--arg1', '--arg2']
tools: ["*"]
env:
ENV_VAR_NAME: ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}
Use type: 'local' (not stdio) in agent files. Secrets support five interpolation syntaxes including $VAR, ${VAR}, ${VAR:-default}, ${{ secrets.VAR }}, and ${{ vars.VAR }}.
SDK Agents (Programmatic)
Defined as CustomAgentConfig objects passed to client.createSession(). See sdk.md for the full API and language-specific examples.
| Field | Required | Notes |
|---|---|---|
name |
Yes | Unique identifier; used in lifecycle events and for pre-selection |
displayName |
No | Human-readable label in events |
description |
No | Agent expertise; the runtime uses this for intent matching |
tools |
No | null or omitted = all session tools; explicit list restricts |
prompt |
Yes | System prompt for this agent's context |
mcpServers |
No | Agent-scoped MCP config; not inherited from session level |
infer |
No | Default true; set false to require explicit invocation |
skills |
No | Skill names resolved from session skillDirectories |