claude-engineering-plugin/docs/specs/copilot.md

GitHub Copilot Spec (Agents, Skills, MCP)

Last verified: 2026-02-14

Primary sources

https://docs.github.com/en/copilot/reference/custom-agents-configuration
https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
https://docs.github.com/en/copilot/concepts/agents/coding-agent/mcp-and-coding-agent

Config locations

Scope	Path
Project agents	.github/agents/*.agent.md
Project skills	.github/skills/*/SKILL.md
Project instructions	.github/copilot-instructions.md
Path-specific instructions	.github/instructions/*.instructions.md
Project prompts	.github/prompts/*.prompt.md
Org/enterprise agents	.github-private/agents/*.agent.md
Personal skills	~/.copilot/skills/*/SKILL.md
Directory instructions	AGENTS.md (nearest ancestor wins)

Agents (.agent.md files)

• Custom agents are Markdown files with YAML frontmatter stored in .github/agents/.
• File extension is .agent.md (or .md). Filenames may only contain: ., -, _, a-z, A-Z, 0-9.
• description is the only required frontmatter field.

Frontmatter fields

Field	Required	Default	Description
name	No	Derived from filename	Display name
description	Yes	—	What the agent does
tools	No	["*"]	Tool access list. [] disables all tools.
target	No	both	vscode, github-copilot, or omit for both
infer	No	true	Auto-select based on task context
model	No	Platform default	AI model (works in IDE, may be ignored on github.com)
mcp-servers	No	—	MCP config (org/enterprise agents only)
metadata	No	—	Arbitrary key-value annotations

Character limit

Agent body content is limited to 30,000 characters.

Tool names

Name	Aliases	Purpose
execute	shell, Bash	Run shell commands
read	Read	Read files
edit	Edit, Write	Modify files
search	Grep, Glob	Search files
agent	Task	Invoke other agents
web	WebSearch, WebFetch	Web access

Skills (SKILL.md)

• Skills follow the open SKILL.md standard (same format as Claude Code and Cursor).
• A skill is a directory containing SKILL.md plus optional scripts/, references/, and assets/.
• YAML frontmatter requires name and description fields.
• Skills are loaded on-demand when Copilot determines relevance.

Discovery locations

Scope	Path
Project	.github/skills/*/SKILL.md
Project (Claude-compatible)	.claude/skills/*/SKILL.md
Project (auto-discovery)	.agents/skills/*/SKILL.md
Personal	~/.copilot/skills/*/SKILL.md

MCP (Model Context Protocol)

• MCP configuration is set via Repository Settings > Copilot > Coding agent > MCP configuration on GitHub.
• Repository-level agents cannot define MCP servers inline; use repository settings instead.
• Org/enterprise agents can embed MCP server definitions in frontmatter.
• All env var names must use the COPILOT_MCP_ prefix.
• Only MCP tools are supported (not resources or prompts).

Config structure

{
  "mcpServers": {
    "server-name": {
      "type": "local",
      "command": "npx",
      "args": ["package"],
      "tools": ["*"],
      "env": {
        "API_KEY": "COPILOT_MCP_API_KEY"
      }
    }
  }
}

Server types

Type	Fields
Local/stdio	type: "local", command, args, tools, env
Remote/SSE	type: "sse", url, tools, headers

Prompts (.prompt.md)

• Reusable prompt files stored in .github/prompts/.
• Available in VS Code, Visual Studio, and JetBrains IDEs only (not on github.com).
• Invoked via /promptname in chat.
• Support variable syntax: ${input:name}, ${file}, ${selection}.

Precedence

1. Repository-level agents
2. Organization-level agents (.github-private)
3. Enterprise-level agents (.github-private)

Within a repo, AGENTS.md files in directories provide nearest-ancestor-wins instructions.