holocron/plugins/kyberforge/skills/write-agent/references/copilot-cli-agents.md

topic, source_keys

topic	source_keys
copilot-cli-agents	github-copilot-custom-agents-config github-blog-copilot-cli-agents

Overview

GitHub Copilot CLI agents are defined as Markdown files with .agent.md extension and YAML frontmatter. They live in the .github/agents/ directory of a repository and are version-controlled with the codebase. Users invoke them via the /agent slash command in the CLI.

File format

---
name: Accessibility Expert
description: Expert assistant for web accessibility (WCAG 2.1/2.2)
model: GPT-4.1
tools:
  - codebase
  - edit/editFiles
  - search
---

# Accessibility Expert

You are a web accessibility expert. Focus on WCAG 2.1/2.2 compliance...

The body (below frontmatter) contains the agent's instructions in Markdown. Maximum 30,000 characters.

Supported frontmatter fields

Field	Type	Required	Description
name	String	Recommended	Display identifier for the agent
description	String	Required	Purpose and capabilities — what this agent does
target	String	No	vscode, github-copilot, or omit for both
model	String	No	Model to use (e.g., GPT-4.1, claude-opus-4-8). Inherits default if unset.
tools	List	No	Tools the agent can use. Defaults to all tools if omitted.
disable-model-invocation	Boolean	No	When true, requires manual agent selection.
user-invocable	Boolean	No	Whether user can manually select this agent. Defaults to true.
mcp-servers	Object	No	Additional MCP server configurations. Not used in VS Code/IDE agents.
metadata	Object	No	Key-value annotation pairs. Not applicable to IDE agents.

Tools field

Tools can be configured three ways:

• All tools (default): omit the tools property, or use tools: ["*"]
• Specific tools: list names, e.g. tools: ["codebase", "edit/editFiles", "search"]
• No tools: tools: []

Available tool aliases (case-insensitive): execute, read, edit, search, agent, web, todo.

MCP server tools use namespacing: mcp-server-name/tool-name or mcp-server-name/* for all tools from a server.

Some available tools: gh, git, codebase, search, githubRepo, runCommands, runTests, edit/editFiles, terraform, conftest, jq, curl, semgrep, trivy, gitleaks.

File location

Copilot CLI agents live in .github/agents/ in the repository root. The filename uses the .agent.md extension (e.g., accessibility.agent.md).

Plugin placement (this repo)

Per the cross-compat reference, plugin agents for Copilot CLI use the .agent.md naming:

• Claude Code reads: agents/<name>.md
• Copilot CLI reads: agents/<name>.agent.md

Both files share the same system prompt body. Only the frontmatter differs: Copilot uses tools: as an array with different tool names; Claude Code uses tools: as comma-separated internal tool names.

Fields not supported in Copilot CLI

These Claude Code agent fields have no Copilot CLI equivalent:

• permissionMode
• maxTurns
• skills (Claude-specific skill injection)
• mcpServers (inline per-agent MCP — not supported in VS Code/IDE)
• hooks
• memory
• background
• effort
• isolation
• color
• initialPrompt
• disallowedTools