Copilot CLI Playbook

A concise guide covering everything you need to know to get started and work effectively with GitHub Copilot CLI.

---

Table of Contents

• How It Works
• Initial Setup and Knowledge
• Best Practices
• Sessions and Memory
• Rules and Permissions
• Skills
• MCPs
• Hooks
• Custom Agents
• Other Useful Info
  • Videos

---

How It Works

Reference: About Copilot CLI

Copilot CLI is an agentic AI assistant that runs in your terminal. It can read files, run commands, edit code, search the web, and interact with GitHub -- all from the command line.

1.1 The Agentic Loop

When you give Copilot a task, it works through a loop of gathering context, taking action, and verifying results -- repeating until the task is complete. You can interrupt at any point to steer it.

1.2 Models

Copilot CLI supports multiple models. Use /model to switch mid-session.

Model	Best For	Notes
Claude Opus 4.5	Complex architecture, difficult debugging	Default model, highest capability
Claude Sonnet 4.5	Day-to-day coding, routine tasks	Fast and cost-effective
GPT-5.2 Codex	Code generation, code review	Good as a second opinion

1.3 Tools

Reference: AI Tools

Tools make Copilot agentic. Without them, it can only respond with text. With them, it can act.

Category	What Copilot Can Do
File operations	Read, edit, create files
Search	Find files by pattern (glob), search content (grep)
Execution	Run shell commands, tests, git operations
Web	Search the web, fetch documentation
GitHub	Access issues, PRs, workflows, Actions via built-in MCP

1.4 What Copilot Can Access

When you run copilot in a directory, it gains access to:

• Your project -- files in the current directory and subdirectories
• Your terminal -- any command you could run (build tools, git, package managers, etc.)
• Your git state -- current branch, uncommitted changes, recent history
• Custom instructions -- .github/copilot-instructions.md, AGENTS.md, CLAUDE.md, etc.
• Extensions -- MCP servers, custom agents, skills

---

Initial Setup and Knowledge

Reference: Getting Started

2.0 Getting Started

1. Get the necessary access via IDM:

   • Order GitHub Enterprise access:
     • In IDM, go to "System Access" → "GitHub"
   • Order GitHub Copilot Enterprise Plan (not GitHub Copilot Business Standalone):
     • In IDM, go to "Order" → "New Order" → "GitHub Teams" → msg.P.ZT.GitHubEnterprise.Copilot

2. Update PowerShell to version 6+:

   Copilot CLI requires PowerShell 6 or later. Install or update via winget:

   winget install --id Microsoft.PowerShell --source winget

   For alternative installation methods, see the official PowerShell installation guide.

3. Install via NPM:

   npm install -g @github/copilot

4. Launch and authenticate:

   copilot

   Inside the CLI, run /login, choose GitHub.com and authenticate.

   Important: In the browser window, make sure to grant GitHub CLI permissions to the necessary organizations and repositories if you want to perform actions on them later.

5. Test it out with a simple prompt: Explain this repository or Tell me something new.

2.1 Custom Instructions

Reference: Custom Instructions

Custom instructions are Markdown files that Copilot reads at the start of every session. Use them to store conventions and context that Copilot cannot infer from code alone.

What to include:

• Build/test/lint commands
• Code style rules that differ from defaults
• Repository etiquette (branch naming, PR conventions)
• Architectural decisions

What to exclude:

• Anything Copilot can figure out by reading code
• Standard language conventions
• Long explanations or tutorials

Supported locations:

Location	Scope
~/.copilot/copilot-instructions.md	All projects (personal)
.github/copilot-instructions.md	Repository-wide
.github/instructions/**/*.instructions.md	Path-specific (with applyTo frontmatter)
AGENTS.md (in git root or cwd)	Repository
CLAUDE.md, GEMINI.md	Repository (also supported)

Run /init to generate starter instructions based on your project.

2.2 Common Commands

Command	Purpose
/init	Generate starter instructions and agentic features
/model	Switch between models
/clear or /new	Reset conversation history
/compact	Summarize conversation to free context
/plan	Create an implementation plan before coding
/diff	Review changes made in the current directory
/review	Run code review agent on changes
/delegate	Push session to Copilot coding agent on GitHub
/add-dir	Add a directory to the allowed list
/context	Visualize current token usage
/usage	Display session usage metrics
/mcp	Manage MCP server configuration
/agent	Browse and select from available agents
/skills	Manage skills
/resume	Switch to a different session
/share	Share session to markdown or GitHub gist
/feedback	Submit feedback to GitHub

2.3 Key Bindings

Reference: Command Reference

Key	Action
@	Add a file/folder to context
!	Run a shell command directly (no model call)
Shift+Tab	Cycle modes (Interactive → Plan → Autopilot)
Ctrl+T	Toggle model reasoning visibility
Esc	Cancel current operation
Ctrl+C	Cancel / clear input / exit
↑ / ↓	Navigate command history

2.4 How to Work Effectively

• Be specific upfront -- reference files with @, mention constraints, point to patterns
• Give verification criteria -- tests, expected outputs
• Explore before implementing -- use Plan mode for complex problems
• Delegate, don't dictate -- give context and direction, trust Copilot with the details
• Interrupt and steer -- send follow-up messages even while Copilot is thinking

2.5 Common Workflow Patterns

Explore → Plan → Confirm → Commit:

Write Tests → Commit → Code → Iterate → Commit:

---

Best Practices

Reference: Best Practices

3.1 The #1 Rule: Give Copilot a Way to Verify Its Work

Include tests, screenshots, or expected outputs so Copilot can check itself. This is the single highest-leverage thing you can do.

3.2 Context Management

Copilot CLI features infinite sessions with automatic context compaction. Still, focused sessions produce better results.

• /clear between unrelated tasks
• /compact to manually compress conversation history
• Use sub-agents for research -- they run in separate context
• Keep custom instructions concise

3.3 Prompting Tips

Reference: Prompt Engineering | Cookbook

Strategy	Before	After
Scope the task	"add tests for foo.py"	"write a test for foo.py covering the edge case where the user is logged out, avoid mocks"
Point to sources	"why is this API weird?"	"look through ExecutionFactory's git history and summarize how its API came to be"
Reference patterns	"add a calendar widget"	"look at how DatePicker is implemented, follow the same pattern for a calendar widget"
Describe symptoms	"fix the login bug"	"users report login fails after session timeout, check src/auth/, especially token refresh"

3.4 Avoid Common Failure Patterns

• Kitchen sink session -- mixing unrelated tasks in one session. Fix: /clear between tasks.
• Correcting over and over -- context polluted with failed approaches. Fix: after 2 failed corrections, /clear and write a better prompt.
• Over-specified instructions -- Copilot ignores half of it. Fix: ruthlessly prune.
• Trust-then-verify gap -- no tests provided. Fix: always provide verification.

---

Sessions and Memory

4.1 Sessions

Each session is an independent conversation tied to your current directory. Sessions save locally and can be resumed.

Action	Command
Resume most recent	copilot --continue
Pick from recent sessions	copilot --resume or /resume
View session info	/session
View session checkpoints	/session checkpoints
View session plan	/session plan
Rename a session	/rename

Session storage:

~/.copilot/session-state/{session-id}/
├── events.jsonl      # Full session history
├── workspace.yaml    # Metadata
├── plan.md           # Implementation plan (if created)
├── checkpoints/      # Compaction history
└── files/            # Persistent artifacts

4.2 Copilot Memory

Reference: Copilot Memory

Copilot Memory is a feature that allows Copilot to store repository-specific learnings ("memories") that persist across sessions. Memories are automatically created as Copilot works and validated against the current codebase before use.

Key points:

• Repository-scoped (not user-scoped) -- shared with all users who have access
• Automatically deleted after 28 days if not revalidated
• Must be enabled in enterprise, organization, or personal settings (off by default)

4.3 Memory Best Practices

• Keep custom instructions specific: "Use 2-space indentation" not "Format code properly"
• Use structured formats: bullet points grouped under descriptive headings
• Review instructions periodically as your project evolves
• Use /instructions to view and toggle active instruction files

---

Rules and Permissions

Reference: Permissions

5.1 Permission System

When Copilot wants to use a tool that could modify or execute files, it asks for approval.

Tool Type	Example	Approval Required
Read-only	File reads, grep, glob	No
Shell commands	Any shell execution	Yes
File modification	Edit/write files	Yes
URL access	Fetching external URLs	Yes

5.2 Permission Modes

Cycle with Shift+Tab:

Mode	Behavior
Interactive (default)	Asks before edits and commands
Plan	Read-only, creates a plan for approval
Autopilot (experimental)	Continues working until task is complete

5.3 Configuration

When prompted for approval, you can:

1. Yes -- allow once
2. Yes, and approve for the rest of the session -- allowlist for this session
3. No (Esc) -- reject and provide alternative instructions

Pre-configure via CLI flags:

copilot --allow-tool 'shell(git:*)' --deny-tool 'shell(git push)'

Common permission patterns:

• shell(git:*) — Allow all Git commands
• shell(npm run:*) — Allow all npm scripts
• write — Allow file writes

Other flags:

• --allow-all or --yolo — Enable all permissions
• --allow-all-paths — Disable path verification
• --allow-all-urls — Disable URL verification

Use /reset-allowed-tools to clear previously approved tools.

---

Skills

Reference: About Agent Skills

6.1 What Is a Skill?

A skill is a folder with a SKILL.md file containing instructions, scripts, and resources that Copilot loads when relevant. Skills teach Copilot to perform tasks in a specific, repeatable way.

6.2 How to Create a Skill

Create a directory with a SKILL.md in .github/skills/ (project) or ~/.copilot/skills/ (personal):

.github/skills/debug-actions/
└── SKILL.md

---
name: debug-actions
description: Guide for debugging failing GitHub Actions workflows
---
To debug failing workflows:
1. Use `list_workflow_runs` to look up recent runs
2. Use `summarize_job_log_failures` for an AI summary of failures
3. If needed, use `get_job_logs` for full logs
4. Reproduce the failure locally
5. Fix and verify before committing

6.3 Where Skills Live

Location	Scope
~/.copilot/skills/ or ~/.claude/skills/	All projects (personal)
.github/skills/ or .claude/skills/	Current project (team-shared)

6.4 Skills vs. Custom Instructions

Use custom instructions for simple, always-relevant rules (coding standards, build commands). Use skills for detailed, task-specific instructions that Copilot should only load when relevant.

Manage skills with /skills.

---

MCPs

Reference: MCP and Coding Agent | Extend with MCP

7.1 What Is an MCP?

MCP (Model Context Protocol) is an open standard for connecting Copilot to external tools, databases, and APIs. MCP servers give Copilot access to services beyond the terminal.

Copilot CLI ships with the GitHub MCP server already configured, enabling interaction with GitHub.com resources (issues, PRs, workflows) out of the box.

7.2 Use Cases

• Query databases (PostgreSQL, etc.)
• Integrate designs from Figma
• Monitor errors with Sentry
• Automate workflows (Slack, Gmail, etc.)

Discover community MCP servers at github.com/mcp.

7.3 How to Configure

# Interactive setup
/mcp add

# Fill in details, press Ctrl+S to save

MCP server details are stored in ~/.copilot/mcp-config.json by default.

Use /mcp to manage servers during a session.

See also: Configuring MCP in Copilot CLI

7.4 Security Concerns

• Use third-party MCP servers at your own risk
• Be cautious with servers that fetch untrusted content (prompt injection risk)
• Review server source and permissions before adding

---

Hooks

Reference: About Hooks | Using Hooks | Hooks Configuration

8.1 What Is a Hook?

A hook is a shell command that executes at specific points during a Copilot session. Hooks are deterministic -- they guarantee the action happens, unlike instructions which are advisory.

8.2 Hook Events

Event	When It Fires
sessionStart	Session begins
sessionEnd	Session terminates
userPromptSubmitted	User sends a prompt
preToolUse	Before a tool call
postToolUse	After a tool call
errorOccurred	An error happens

8.3 How to Configure

Create a hooks.json file in .github/hooks/:

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "echo \"Session started: $(date)\" >> logs/session.log",
        "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
        "timeoutSec": 10
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "./scripts/post-tool.sh",
        "cwd": "scripts"
      }
    ]
  }
}

For Copilot CLI, hooks are loaded from your current working directory. For Copilot coding agent on GitHub, they must be on the default branch.

---

Custom Agents

Reference: About Custom Agents

9.1 What Is a Custom Agent?

A custom agent is a specialized version of Copilot that you tailor to specific workflows, conventions, and use cases. Defined via Markdown files called agent profiles, they encode your standards, tools, and practices.

9.2 Built-in Agents

User-controllable agents (invoked with slash commands):

Agent	Command	Purpose
Plan	/plan	Analyze dependencies and structure to create implementation plans
Code-review	/review	Review changes, surfacing only genuine issues

Behind-the-scenes agents (automatically invoked by Copilot when needed):

Agent	Purpose
Explore	Quick codebase analysis without adding to main context
Task	Execute commands (tests, builds), brief summary on success, full output on failure

9.3 How to Create Your Own

Create a Markdown file with YAML frontmatter in .github/agents/:

---
name: readme-creator
description: Agent specializing in creating and improving README files
---

You are a documentation specialist focused on README files.

- Create and update README.md files with clear project descriptions
- Structure sections logically: overview, installation, usage, contributing
- Use relative links for files within the repository

9.4 Where Agents Live

Type	Location	Scope
Personal	~/.copilot/agents/	All projects
Repository	.github/agents/	Current project
Organization/Enterprise	/agents/ in .github-private repo	All org/enterprise projects

Use /agent to browse and select from available agents during a session.

---

Other Useful Info

Videos

• Guide to GitHub Copilot CLI
• Demo: Using GitHub Copilot CLI
• Configuring MCP in Copilot CLI
• Switch models in GitHub Copilot CLI

10.2 Delegate to Copilot Coding Agent

Reference: Using delegate in Copilot CLI

The /delegate command pushes your current session to Copilot coding agent on GitHub to run in the cloud.

/delegate Add dark mode support to the settings page

Copilot commits any unstaged changes, creates a branch, opens a draft PR, and works in the background.

Use /delegate	Work locally
Tangential tasks	Core feature work
Documentation updates	Debugging
Refactoring separate modules	Interactive exploration

10.3 Programmatic Usage

Reference: Copilot: Modes of Use

Run Copilot non-interactively with --prompt or -p:

# Simple query
copilot -p "Explain what this project does"

# Specify an agent
copilot --agent=refactor-agent --prompt "Refactor this code block"

# Continue a previous session
copilot -p "Now fix the edge cases" --continue

10.4 IDE Integrations

• VS Code Extension
• JetBrains Plugin
• Eclipse, Xcode (public preview)

10.5 Multi-Repository Workflows

# Option 1: Run from a parent directory
cd ~/projects && copilot

# Option 2: Add directories during a session
/add-dir /path/to/backend-service
/add-dir /path/to/shared-libs

View allowed directories with /list-dirs.

10.6 Documentation and Resources

• Official Docs
• Best Practices
• Command Reference
• Prompt Cookbook

10.7 Troubleshooting

Issue	Solution
Permission prompts too frequent	Approve for the session, or use --allow-tool
Authentication problems	/logout, restart, re-authenticate or use /login
Context filling up	Use /compact, /clear between tasks
General help	Run copilot help or /help
Submit feedback	/feedback