Copilot CLI Handbook

Last updated on June 15, 2026 at 7:30 PM EDT

Custom instructions, commands, permissions, agents, hooks, configuration, and MCP for GitHub Copilot CLI

Instruction Files

Copilot CLI can load repository, path-specific, agent, and local instructions from several official file locations. How-to: custom instructions

Common instruction locations

Useful commands and flags

Interactive Commands

Session and navigation

Planning, review, and collaboration

Agents, models, skills, and plugins

Tools, account, and setup

Keyboard shortcuts

Command-Line Commands and Flags

Core commands

Automation and session control

Permissions and safety

UI, output, and logging

MCP and tooling flags

Permission Prompts and Tool Rules

When Copilot CLI asks for permission, these one-key responses are available. Docs: permission approvals

Tool rules use the Kind(argument) pattern. Deny rules always override allow rules. Available kinds include shell, read, write, url, memory, and SERVER-NAME. Shell commands that set dynamic-loader or git-config environment variables (e.g. LD_PRELOAD, GIT_EXTERNAL_DIFF) prompt for approval before running. Docs: tool rules Release: v1.0.60

# Allow all git commands except git push
copilot --allow-tool='shell(git:*)' --deny-tool='shell(git push)'

# Allow one MCP tool
copilot --allow-tool='MyMCP(create_issue)'

# Allow all tools from one MCP server
copilot --allow-tool='MyMCP'

Examples adapted from the command reference. Docs: tool rules

Configuration Files

Settings cascade from broader scopes to narrower scopes. Command-line flags and environment variables always win. Docs: config settings

Common user settings

Repository-level settings

Repository settings support shared plugin behavior and startup messaging. Docs: repo settings

Hooks

Hook configuration files live in .github/hooks/*.json in the current working directory. User-level hook scripts can also live in ~/.copilot/hooks/, and ~/.copilot/config.json supports inline user-level hook definitions. Docs: hooks reference How-to: hooks Docs: config dir

What hooks can do

Main hook events

Hook formats

Useful recent hook updates

MCP Servers

Copilot CLI can load MCP servers from several places. Docs: MCP config

Configuration sources

CLI only reads .mcp.json for project-level MCP config. If a .vscode/mcp.json is detected without a .mcp.json, a migration hint appears with a jq command to convert. Release: v1.0.22

Built-in MCP servers

Transport types

Common fields

MCP Tasks (experimental)

MCP tools with taskSupport: "required" run as non-blocking background agents, trackable via list_agents and read_agent. Available when experimental mode is enabled. Release: v1.0.41

MCP server registry

MCP servers can be installed from the registry with guided configuration directly in the CLI. Release: v1.0.25

Trust model

All MCP tool calls still require explicit permission, including read-only calls against external services. Docs: MCP trust

MCP server names can contain any printable characters, including spaces and Unicode. Control characters and } are not allowed. Tool names are sanitized (invalid characters become -, Unicode is Punycode-encoded, 64-character limit). Docs: MCP config

GitHub Enterprise organizations can enforce an MCP server allowlist. When active, the CLI evaluates each non-default server fingerprint against the enterprise policy before connecting. Docs: MCP config

Skills and Custom Agents

Skills

Skills are Markdown files that extend what Copilot CLI can do. Each skill lives in its own directory with a SKILL.md file. Docs: skills

Built-in skills are now included with the CLI, starting with guides for common tasks. Release: v1.0.17

Common skill locations:

Useful frontmatter fields:

Commands are an alternative skill format stored as individual .md files in .claude/commands/. The command name is derived from the filename. Command files use a simplified format (no name field required) and support description, allowed-tools, and disable-model-invocation. Commands have lower priority than skills with the same name. Docs: skills

Skill instructions persist correctly across conversation turns. Release: v1.0.25

Custom instructions and skills refresh from disk after /clear or /new. Release: v1.0.28

Skills that exceed the token limit are still discoverable and invocable by name. Release: v1.0.32

Custom agents and skills are now discovered recursively in subdirectories. Release: v1.0.55

--plugin-dir skills now take precedence over ~/.copilot and ~/.agents skills with the same name. Discovery order: project > plugin-dir > personal > custom. Release: v1.0.55

Custom agents

Custom agents are specialized AI agents defined in Markdown files. You can browse them with /agent or select one up front with --agent=AGENT. Docs: custom agents Docs: slash commands Docs: CLI options

Built-in agents currently include:

Custom agent locations:

Useful frontmatter fields:

Custom agents in nested .github/agents and .claude/agents directories are discovered when the session starts from a subdirectory of the repository root. Release: v1.0.62

Plugins can ship extensions, installable via the plugin marketplace. Session-scoped extensions and canvases are also available. Release: v1.0.62

Use /settings to browse and edit all user settings in an interactive dialog. Docs: slash commands Release: v1.0.61

Environment Variables

Useful environment variables include:

Observability

Copilot CLI can export traces and metrics with OpenTelemetry. Docs: OTel

Recent Additions Worth Knowing

Recent official releases added or improved several user-facing CLI features.

v1.0.62

v1.0.61

v1.0.60

v1.0.59

v1.0.58

v1.0.57

v1.0.56

v1.0.55

v1.0.52

v1.0.51

v1.0.49

v1.0.47

v1.0.46

v1.0.45

v1.0.44

v1.0.43

v1.0.42

v1.0.41

v1.0.40

v1.0.39

v1.0.37

v1.0.36

v1.0.35

v1.0.32

v1.0.30

v1.0.29

v1.0.28

v1.0.27

v1.0.26

v1.0.25

v1.0.24

v1.0.23

v1.0.22

v1.0.21

v1.0.20

v1.0.17

v1.0.16

v1.0.15

v1.0.14

v1.0.13

Earlier releases

Sources