GitHub Copilot
Customization File Reference

Verified against docs.github.com/copilot and code.visualstudio.com/docs — Copilot ships weekly; re-check sources before relying on specifics.

Compiled by VerySmartParrot · an independent community reference

✓ Source-linked verified June 12, 2026 · live docs Unofficial community reference
📘 Documented described in GitHub's or VS Code's official docs ⚙ Convention observed pattern or workaround, not a documented spec
How to read this tree. This shows Copilot customization files across repository, user, editor, GitHub.com, and plugin scopes. A real project would only use the parts it needs. The my-plugin/ layout has its own 🔌 Plugin tab. Click any row for details.
MD Markdown
JSON Config
YML Workflow / prompt config
SCRIPT Hook/Skill
WEB GitHub.com setting
LOCAL Gitignored
my-project/
AGENTS.mdMD← agent instructions; nearest wins for GitHub cloud agent
CLAUDE.md / GEMINI.mdMD← root-only cloud-agent compatibility files
.gitignoreCFG
.envLOCAL
🏠 .github/ — Copilot's home in the repo
.github/← shared team config
copilot-instructions.mdMD← repo-wide instructions
instructions/MD← path-scoped instructions
frontend.instructions.mdMD← applyTo: "src/**/*.tsx"
terraform.instructions.mdMD← applyTo: "**/*.tf"
prompts/MD← reusable prompts
code-review.prompt.mdMD→ /code-review
new-component.prompt.mdMD→ /new-component
summarizer.prompt.ymlYML← GitHub Models prompt/eval asset; location flexible
agents/MD← custom agents
api-architect.agent.mdMD← persona + tools + prompt
test-specialist.agent.mdMD
skills/MD← agent skills
webapp-testing/← one folder per skill
SKILL.mdMD← instructions + frontmatter
run-tests.shSCRIPT← bundled script
references/← deep reference docs
hooks/JSON← lifecycle hooks
quality-gates.jsonJSON← any NAME.json hook file
workflows/← setup + agentic workflows
copilot-setup-steps.ymlYML← cloud agent env setup
daily-repo-status.mdMD← GitHub Agentic Workflow source
daily-repo-status.lock.ymlYML← compiled workflow
copilot/JSON← settings.json + settings.local.json (CLI)
Interop with official support: GitHub documents one or more AGENTS.md files anywhere in the repo, with the nearest file taking precedence for agent work. Root CLAUDE.md and GEMINI.md are documented alternatives for supported cloud-agent surfaces; VS Code additionally documents Claude-compatible locations.
💻 Workspace (VS Code)
.vscode/← editor workspace config
mcp.jsonJSON← workspace MCP servers
settings.jsonJSON← chat.* / copilot settings
💻 Your Code
src/← your actual code
AGENTS.mdMD← optional subtree-specific agent instructions
👤 User-Level (Copilot CLI)
~/.copilot/← CLI home (relocatable)
settings.jsonJSON← CLI settings (was config.json)
mcp-config.jsonJSON← user MCP servers
copilot-instructions.mdMD← personal global instructions
instructions/MD
code-style.instructions.mdMD
agents/MD← personal agents
reviewer.agent.mdMD
skills/MD← personal skills
hooks/JSON← personal CLI hooks
session-state/ · logs/AUTO← managed by the CLI
~/.agents/skills/MD← cross-tool personal skills
🌐 GitHub.com Settings (not files)
Several Copilot layers are web settings, not files in any repo. They're shown here so the map is complete.
Personal custom instructionsWEB← highest priority
Organization custom instructionsWEB← lowest priority
Repo → Settings → CopilotWEB← cloud agent MCP + secrets
Content exclusionWEB← hide paths for documented chat/review surfaces
📂

Select a file or folder

Click any item in the tree to see its description, usage examples, and source documentation.

Navigate with Tab and Enter, or close with Esc.

Preview in VS Code. Agent plugins are in preview in VS Code (chat.plugins.enabled). GitHub also documents Copilot CLI plugin commands and references, but absence of a preview label is not treated here as a release-status guarantee. Expect details to shift between releases.

A plugin is a folder bundling skills, custom agents, slash commands, hooks, and MCP servers into one installable unit. The Copilot CLI structure is documented in GitHub Docs; VS Code documents the same plugin surface as preview. Installed plugins appear alongside your locally defined customizations.

Is plugin.json required? Yes — Copilot-format plugins require a root plugin.json manifest, and name is the required field. Keep names valid and boring; invalid manifests may prevent discovery depending on the host.
Documented plugin structure
my-testing-plugin/← one folder = one plugin
plugin.jsonJSON← required manifest
skills/MD← on-demand skills
test-runner/
SKILL.mdMD← instructions + frontmatter
run-tests.shSCRIPT← supporting script
agents/MD← custom agents
test-reviewer.agent.mdMD← read-only review persona
commands/MD← optional slash-command files
review.mdMD← plugin command entry point
hooks.jsonJSON← Copilot-format plugin hooks
hooks/JSON← alternate/Claude-format hooks
hooks.jsonJSON← hooks/hooks.json is also documented
scripts/SCRIPT
validate-tests.shSCRIPT← hook script
.mcp.jsonJSON← MCP server definitions
lsp.jsonJSON← optional LSP server definitions
🛒 Marketplace repos
marketplace.jsonJSON← indexes plugins in a repo
Cross-tool compatibility: Copilot, Claude-format, and OpenPlugin manifests are all recognized by documented plugin loaders, but each format has its own manifest and hook paths. Security: plugins can ship hooks and MCP servers that run code on your machine; review contents and publisher before installing, especially from community marketplaces.
🔌

Select a plugin file

Click any item in the plugin tree to see what it does, example content, and a link to the official source.

Navigate with Tab and Enter, or close with Esc.

Copilot customization file types, grouped by format and surface. Naming does much of the routing: *.instructions.md is automatic context when applicable, *.prompt.md is on-demand, *.agent.md is a persona, and SKILL.md is a capability. GitHub Models *.prompt.yml files are included separately because they are prompt/evaluation assets, not Copilot slash commands.

MD — Instructions (always-on context)

📋 copilot-instructions.md MD

Repo-wide instructions in .github/. Loaded on every chat request in the repo, across IDEs, the cloud agent, and code review. Generate one with /init in VS Code.

# Project conventions - TypeScript strict mode, no `any` - Build: `npm run build` · Test: `npm test` - Conventional Commits (feat:, fix:, chore:)

📝 *.instructions.md MD

Path-scoped instructions with an applyTo glob in the frontmatter. GitHub and VS Code both merge applicable instruction files; VS Code does not guarantee an ordering among multiple project instruction files, so avoid contradictions.

--- applyTo: "src/**/*.{ts,tsx}" description: Frontend conventions --- - Functional components + hooks only - Tailwind for styling, no inline CSS

📋 AGENTS.md MD

A cross-tool-compatible agent instruction file. GitHub documents one or more AGENTS.md files anywhere in a repo, with the nearest file winning for cloud-agent work; VS Code supports root AGENTS.md and treats nested files as experimental. GitHub Docs also recognize root CLAUDE.md and GEMINI.md as cloud-agent compatibility inputs.

📋 ~/.copilot/copilot-instructions.md MD

Personal global instructions for the Copilot CLI — same format as the repo file, applied to every session regardless of project. Extra topic files go in ~/.copilot/instructions/.

MD — Prompts, Agents & Skills (on-demand)

📝 *.prompt.md MD

A reusable task you invoke explicitly with /name in supported IDE chats. Frontmatter can pin a description, model, tools, and agent. VS Code documents prompt files as workspace/user customizations; verify other IDE support before publishing a surface claim.

--- description: Review code for security issues agent: agent --- Review ${selection} for OWASP Top 10 issues. Report findings as a checklist.

🧪 *.prompt.yml / *.prompt.yaml YML

GitHub Models prompt and evaluation files, not Copilot slash-command prompt files. They can live anywhere in the repository and carry messages, testData, and evaluators for repeatable prompt tests.

name: Text Summarizer model: openai/gpt-4o-mini messages: - role: system content: Summarize support input. testData: - input: App crashes on upload expected: Upload crash reported evaluators: - name: Starts concise string: { startsWith: "Upload" }

🤖 *.agent.md MD

A custom agent profile. GitHub's cloud-agent reference requires description and documents a 30,000-character prompt limit; VS Code accepts a broader optional frontmatter set. Prefer .agent.md; GitHub also accepts plain .md in .github/agents/.

--- name: api-architect description: Designs REST endpoints tools: ['search', 'edit'] --- You are an API design specialist. Follow the spec in docs/api-standards.md.

📝 *.chatmode.md MD

Legacy. "Custom chat modes" were renamed to custom agents. Rename files to .agent.md and move them to the agents location to continue using them.

📝 SKILL.md MD

The core file of an agent skill. The name and description frontmatter identify the skill and help Copilot decide when to load it; bundled scripts and references load progressively. Keep the folder and name aligned because hosts use both for discovery.

--- name: webapp-testing description: Use when writing or running tests for the web app. Triggers on "test", "E2E", "coverage". --- 1. Analyze code, pick a test strategy 2. Follow AAA pattern; run ./run-tests.sh
JSON — Configuration & Manifests

🔌 .vscode/mcp.json JSON

Workspace MCP servers for VS Code. Commit it to share tools with the team; use inputs for secrets instead of hard-coding them.

{ "servers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } }

🔌 MCP placement map JSON

Do not publish .mcp.json as a general Copilot repository MCP file. Current docs split MCP by surface: VS Code uses .vscode/mcp.json, Copilot CLI uses ~/.copilot/mcp-config.json, GitHub cloud agent/code review use repository settings, and plugins may contain .mcp.json or .github/mcp.json.

🔌 ~/.copilot/mcp-config.json JSON

User-level MCP servers for the CLI, available in every session. Managed via /mcp slash commands or edited directly.

🪝 hooks/*.json / hooks.json JSON

Maps agent lifecycle events to shell commands. Repo/user hooks are JSON files such as .github/hooks/quality-gates.json or ~/.copilot/hooks/audit.json; Copilot-format plugins can use root hooks.json. Requires top-level "version": 1.

{ "version": 1, "hooks": { "preToolUse": [{ "type": "command", "bash": "scripts/validate-tests.sh" }] } }

📋 plugin.json JSON

Required plugin manifest. Only name is mandatory (kebab-case, max 64 chars). Component paths default to skills/, agents/, etc.

⚙️ .vscode/settings.json JSON

Workspace settings that steer discovery and feature toggles: chat.instructionsFilesLocations, chat.promptFilesLocations, chat.agentFilesLocations, chat.agentSkillsLocations, chat.useAgentsMdFile, chat.useNestedAgentsMdFiles, chat.useClaudeMdFile, chat.useCustomizationsInParentRepositories, plus MCP/plugin toggles.

⚙️ ~/.copilot/settings.json JSON

Copilot CLI settings. Anything still in the older config.json is migrated here automatically on startup.

MD/YML — Agentic Workflows & Cloud Agent Environment

🤖 .github/workflows/*.md MD

GitHub Agentic Workflow source files. They combine YAML frontmatter with natural-language instructions, run AI agents in GitHub Actions, and are compiled with gh aw compile into matching *.lock.yml workflows.

--- on: schedule: daily permissions: issues: read safe-outputs: create-issue: title-prefix: "[status] " --- # Daily repository status Summarize issues, PRs, CI, and risks.

🔒 .github/workflows/*.lock.yml YML

Generated GitHub Actions workflow produced from an Agentic Workflow Markdown file. GitHub's gh-aw reference says to commit lockfiles for transparency and not edit them directly; frontmatter changes require recompilation.

⚙️ copilot-setup-steps.yml YML

A GitHub Actions workflow in .github/workflows/ that pre-installs your toolchain before the cloud agent starts. The job must be named copilot-setup-steps. The single highest-leverage file for agent reliability: if the agent can build and test, it can verify its own work.

name: Copilot Setup Steps on: workflow_dispatch jobs: copilot-setup-steps: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: { node-version: 22 } - run: npm ci
WEB — GitHub.com Settings (no file in the repo)

🌐 Personal instructions WEB

Set in your GitHub.com Copilot settings. Apply only to Copilot Chat on GitHub.com (not IDEs), and where they apply take the highest priority of all instruction layers.

🌐 Organization instructions WEB

Set by org owners (Copilot Business/Enterprise). Applied across the org's repos, but at the lowest priority — guidance, not enforcement.

🌐 Cloud agent MCP config WEB

JSON pasted into Repo → Settings → Copilot. MCP tools configured here run autonomously, without approval prompts. Secrets come from Agents secrets named COPILOT_MCP_*.

🌐 Content exclusion WEB

Repo/org/enterprise path rules (Copilot Business/Enterprise) that hide files from documented completion, chat, and code-review context. GitHub documents that IDE Edit/Agent modes do not support content exclusion. Configured in settings, not in a dotfile — there is no .copilotignore.

SCRIPT & LOCAL

🪝 scripts/*.sh SCRIPT

Shell scripts referenced by hook JSON files. Hooks receive event JSON on stdin; preToolUse (and the CLI-only permissionRequest) can deny a tool call, and stop hooks can block completion.

🪝 Skill scripts SCRIPT

Executables bundled inside a skill folder. Loaded only when the skill activates — the "resources" stage of progressive disclosure.

🔑 .env LOCAL

Secrets and environment values. Gitignore it. Content exclusion is not a secret-management control for autonomous agents; keep real credentials out of the working tree and provide them through documented secret/variable mechanisms.

Five layers, from organization-wide to plugin-installed. Click any file path to see its full description. Note the inversion: in Copilot, personal instructions outrank organization instructions.

🏢 1. Organization / Enterprise

GitHub.com settings (no files in any repo)
  • Org custom instructions (Copilot Business/Enterprise)
  • Org-level custom agents (managed by GitHub/org policy; VS Code discovery can be enabled)
  • MCP allow policies & Agents secrets/variables
  • Content exclusion rules

Managed by org owners. Org instructions are merged in at the lowest priority — they guide, they don't override. Hard enforcement comes from policies, content exclusion, and hooks instead.

Lowest instruction priority

👤 2. Personal / User

  • GitHub.com personal instructions (highest priority)
  • ~/.copilot/copilot-instructions.md
  • ~/.copilot/instructions/*.instructions.md
  • ~/.copilot/agents/*.agent.md
  • ~/.copilot/skills/ or ~/.agents/skills/
  • ~/.copilot/mcp-config.json
  • ~/.copilot/settings.json

Your preferences across all projects — web settings for chat everywhere, ~/.copilot/ for the CLI, the VS Code user profile for editor-level instructions/prompts/agents.

All your projects

📁 3. Repository (Shared)

  • .github/copilot-instructions.md
  • .github/instructions/*.instructions.md
  • AGENTS.md anywhere in the repo (nearest wins for GitHub cloud agent; nested is VS Code experimental)
  • CLAUDE.md / GEMINI.md at repo root (cloud-agent compatibility inputs)
  • .github/prompts/*.prompt.md
  • *.prompt.yml / *.prompt.yaml (GitHub Models; anywhere in repo)
  • .github/agents/*.agent.md
  • .github/skills/ (also .claude/skills/, .agents/skills/)
  • .github/hooks/*.json
  • .github/workflows/*.md (GitHub Agentic Workflows)
  • .github/workflows/*.lock.yml (compiled by gh aw)
  • .github/workflows/copilot-setup-steps.yml
  • .vscode/mcp.json
  • .github/copilot/settings.json (CLI)

Committed to git. Shared by the team, but surface support varies across GitHub.com, cloud agent, code review, CLI, and VS Code.

Team sharedCommitted to git

🔒 4. Local (Personal, not committed)

  • .env and other gitignored secrets
  • .github/copilot/settings.local.json (gitignored CLI config overrides)
  • ~/.copilot/session-state/, logs/ (auto-managed)
  • Relocate ~/.copilot/ via COPILOT_HOME (documented; XDG_CONFIG_HOME is a community workaround)

Copilot has no documented equivalent of CLAUDE.local.md for instructions. The closest thing is the CLI's gitignored per-repo config file .github/copilot/settings.local.json (personal overrides of the committed .github/copilot/settings.json). Personal instruction layering happens at the user level (web settings, ~/.copilot/, VS Code profile) instead.

Gitignored

🔌 5. Plugin Layer

  • plugin/plugin.json (required)
  • plugin/skills/
  • plugin/agents/
  • plugin/commands/
  • plugin/hooks.json or plugin/hooks/hooks.json
  • plugin/.mcp.json
  • plugin/lsp.json or plugin/.github/lsp.json
  • marketplace.json (marketplace repos)

Installed plugins surface their skills, agents, commands, hooks, and MCP servers alongside your local ones. Documented for the Copilot CLI and marked preview in VS Code (chat.plugins.enabled).

Installable bundlePreview in VS Code
Instruction priority (conflict resolution)
# Documented instruction precedence is intentionally coarse:
Personal instructions on GitHub.com outrank repository instructions, which outrank organization instructions where those web layers apply.
VS Code documents personal → repository → organization, but also says no specific order is guaranteed among multiple project instruction files.
GitHub cloud agent uses the nearest AGENTS.md in the directory tree; root CLAUDE.md/GEMINI.md are alternatives for supported cloud-agent surfaces.
The Copilot CLI support matrix lists AGENTS.md for agent instructions, so avoid claiming CLAUDE.md/GEMINI.md work everywhere.

# Code review reads instructions from the BASE branch, not the PR branch.
🌐

Select a file path

Click any file in the scope cards to see what it does, with examples and source links.

Navigate with Tab and Enter, or close with Esc.

Everything here is traceable to GitHub's or VS Code's official documentation, changelogs, or public repositories. Each detail card links its own source; the full set is below.

📘 Last verified June 12, 2026 against live docs. Copilot has no version pin to cite — it's a continuously shipped service. Items marked ⚙ are observed conventions or examples, not documented guarantees. VS Code agent plugins and GitHub Agentic Workflows are explicitly marked preview.

How to read the badges

📘 Documented featureDescribed in GitHub's or VS Code's official docs (linked on the card).
⚙ ConventionObserved pattern or community workaround. Useful, not a documented spec.

📘 Normative GitHub Docs

📘 Normative VS Code Docs

📦 Source Repositories & Examples

⚠ Known Caveats

  • Naming churn: "chat modes" → "custom agents"; "coding agent" → "cloud agent". Older docs and blog posts use older names.
  • Instruction precedence is only documented at broad layer level. Avoid contradictory repo-wide, path-specific, and agent-instruction files instead of depending on undocumented ordering.
  • Copilot code review reads instructions from the base branch and only the first 4,000 characters of any custom-instruction file.
  • Code review ignores some file categories separately from content exclusion, including dependency-management files, logs, and SVGs.
  • .github/chatmodes/*.chatmode.md is legacy VS Code terminology. Current docs use custom agents in .github/agents/.
  • GitHub Models *.prompt.yml/*.prompt.yaml files are adjacent prompt/evaluation assets, not Copilot .prompt.md slash commands.
  • Cloud-agent/code-review MCP supports MCP tools, not MCP resources or prompts; default GitHub and Playwright MCP servers are documented.
  • MCP tools configured for the cloud agent run autonomously, without approval prompts.
  • GitHub Agentic Workflows are in public preview; commit both the Markdown source and generated lockfile, and recompile after frontmatter changes.
  • CLI custom-agent precedence is inconsistent across current official pages; this reference calls that out instead of claiming a stable rule.
  • Surface support varies per feature and changes often; every detail card links its evidence source.

🔍 What's Intentionally Not Shown

  • CLI LSP server config and internal state internals such as command-history and plugin metadata caches.
  • Copilot Extensions, Copilot Spaces, and memory settings — important, but not hand-authored file structures.
  • Full content-exclusion syntax — it lives in web settings; this page maps existence and agentic caveats.
  • Exact VS Code user-profile storage paths for personal instructions/prompts/agents — managed through the UI/profile system.
  • This is a map of what each file does, not a byte-level schema spec.