Copilot Configuration Manager

You help the user manage all GitHub Copilot CLI configuration files.

Config file map

What	File	Scope
User settings (model, theme, URLs, hooks, ...)	~/.copilot/settings.json	Global
Repository settings (limited keys)	.github/copilot/settings.json	Project (committed)
Local settings (limited keys)	.github/copilot/settings.local.json	Project (gitignored)
Trusted folders, auth state	~/.copilot/config.json (trustedFolders)	Global
Saved tool/directory approvals	~/.copilot/permissions-config.json	Global, per location
MCP servers	~/.copilot/mcp-config.json	Global
MCP servers	.mcp.json or .github/mcp.json	Project
LSP servers	~/.copilot/lsp-config.json / .github/lsp.json	Global / Project
BYOK providers	~/.copilot/providers.json	Global
Hooks	~/.copilot/hooks/<name>.json or hooks in settings.json	Global
Hooks	.github/hooks/<name>.json or hooks in repo settings	Project
Skills	~/.copilot/skills/<name>/SKILL.md (or ~/.agents/skills/)	Global personal
Skills	.github/skills/, .agents/skills/, .claude/skills/	Project
Custom agents	~/.copilot/agents/<name>.agent.md	Global personal
Custom agents	.github/agents/ or .claude/agents/	Project
Plugins	~/.copilot/installed-plugins/ (manage via copilot plugin)	Global
Custom instructions	~/.copilot/copilot-instructions.md, ~/.copilot/instructions/**/*.instructions.md	Global personal
Custom instructions	.github/copilot-instructions.md, AGENTS.md, CLAUDE.md, GEMINI.md	Project
Path-specific instructions	.github/instructions/**/*.instructions.md	Project (applyTo glob)
Model allowlist	.github/allowed_models.txt	Project

Config directory override: set COPILOT_HOME to replace ~/.copilot entirely (--config-dir is deprecated). User preferences belong in settings.json; user-setting keys left in config.json are ignored, and config.json keeps only internal state such as trusted folders.

Workflow

1. Identify the task → use the task-to-reference map below to load only what you need
2. Read the target file first before making any changes
3. Edit safely → use the Edit tool for targeted changes; validate JSON after editing
4. Confirm → show the user exactly what changed

Task → Reference map (load only what's needed)

Task	Reference file
settings.json keys (user, repo, local), config directory layout	references/config-schema.md
Trusted folders, config.json	references/config-schema.md §config.json
Environment variables	references/config-schema.md §Environment variables
OpenTelemetry export, managed telemetry	references/config-schema.md §OpenTelemetry monitoring
Authentication, tokens	references/config-schema.md §Auth
BYOK models / custom providers, model selection	references/config-schema.md §BYOK, §Model usage
Tool/path/URL permissions, permissions-config.json, sandbox, plan-mode and shell safety checks	references/permissions.md
CLI flags, slash commands, supported model IDs, sessions (--name, --resume), debug logs	references/cli-commands.md
MCP servers, LSP servers	references/mcp.md
Hooks, including agent-scoped hooks in custom agent frontmatter	references/hooks.md
Skills	references/skills.md
Custom agents, subagents, plugins, marketplaces	references/agents-plugins.md
Custom instructions	references/instructions.md

Common quick operations (no reference needed)

# Trust a folder permanently: add its path to "trustedFolders" in ~/.copilot/config.json

# Change a setting (inside a session)
/settings                     # editor; /settings KEY VALUE sets inline
/settings show model

# Read or change a setting from the terminal (user file by default; --repo / --local available)
copilot config theme
copilot config footer.showQuota off
copilot config --list

# Check auth
/user show                    # inside a session; copilot login to sign in

# MCP servers
copilot mcp list              # terminal; /mcp list inside a session

# Skills
copilot skill list            # terminal; /skills list inside a session

# Model
/model                        # inside a session; or copilot --model=auto

# Permissions for this session
copilot --allow-tool='shell(git:*)' --deny-tool='shell(git push)'
/allow-all                    # alias for /permissions allow-all

# Sandbox shell commands (macOS, Linux, Windows)
copilot --sandbox             # this session only; /sandbox enable saves the setting

# Offline mode (BYOK only, no GitHub contact)
export COPILOT_OFFLINE=true

# Name and resume sessions
copilot --name my-feature-work
copilot --resume=my-feature-work
/session delete [ID]          # or /session delete-all

# Prevent system sleep during long sessions
/keep-alive on                # on | off | busy | DURATION

# Remote control (--no-remote is removed and --remote no longer works for interactive or -p startup; it remains only for legacy --server/--headless; remoteSessions: true makes it the default)
/remote on
/remote off

# Session-history syncing and client telemetry, one run only
copilot --sync-session=off
copilot --disable-client-telemetry

# What's loaded right now (instructions, MCP, skills, agents, hooks, plugins)
/env

Scripts

• scripts/show-config.py — display all config files with annotations
• scripts/update-references.py — fetch latest upstream docs

Run with: python scripts/<script>.py

Self-update procedure

When the user asks to update, refresh, or sync this skill:

1. Run python scripts/update-references.py --all → fetches each configured reference source to _fetched/
2. If the script exits nonzero, resolve the reported failures and rerun it; do not use a partial _fetched/ set as source material
3. Read each _fetched/ file alongside its corresponding references/ file
4. Update references/ files to reflect documentation changes
5. Delete _fetched/ and report what changed

Source URLs are in sources.json.

Safety rules

• Always read the file before editing
• Never remove trustedFolders entries without confirming with the user
• Hooks and skills live in project directories — confirm scope (global vs project) before creating
• Don't edit permissions-config.json while a Copilot CLI session is running
• JSON files: validate well-formed after any edit (settings.json also accepts JSONC comments)
• Hook, instruction, and custom-agent changes apply only after restarting (or resuming) the CLI; skills, MCP, and LSP can use /skills reload, /mcp reload, /lsp reload
• Markdown files: preserve frontmatter structure