| name | copilot-customization |
| description | Authoritative reference for VS Code Copilot customization mechanisms: instructions, prompt files, custom agents, agent skills, MCP servers, hooks, and plugins. Use when deciding which customization type to use, creating new .instructions.md/.prompt.md/.agent.md/SKILL.md/mcp.json files from scratch, or debugging why a customization is not loading. DO NOT USE FOR: routine file edits where the format is already known. |
| license | MIT |
Copilot Customization
Quick-reference for the full VS Code GitHub Copilot customization surface.
Deep-dive content lives in references/ — load on demand, not all at once.
When to Use This Skill
- Deciding which customization mechanism fits a new requirement
- Creating a new customization file from scratch (need the frontmatter schema)
- Debugging why an instruction/skill/agent/prompt is not loading
- Reviewing a customization file for spec compliance
- Comparing mechanisms (instructions vs skills vs agents vs prompts)
Do NOT load this skill for routine edits to existing files where you already know the format.
For enforcement rules, use the instruction files directly (they auto-load via applyTo globs).
Quick Decision Tree
I want to...
├── Define coding standards for ALL files
│ → .github/copilot-instructions.md (always-on)
│
├── Define rules for SPECIFIC file types (by glob)
│ → .instructions.md with applyTo (auto-loaded when files match)
│
├── Store reference content agents read ON DEMAND (not always-on)
│ → SKILL.md with references/ directory
│
├── Create a reusable task I invoke manually with /name
│ → .prompt.md (slash command)
│
├── Create a specialized AI persona with its own tools
│ → .agent.md (custom agent)
│
├── Connect to external tools, APIs, or databases
│ → mcp.json (MCP server)
│
├── Run code at agent lifecycle points (block tools, auto-format)
│ → hooks/*.json (Preview — verify with live docs)
│
└── Bundle multiple customizations for distribution
→ agent plugin (Preview — verify with live docs)
The 7 Customization Mechanisms
| # | Mechanism | File Type | Loading | Scope | Portability |
|---|
| 1 | Custom Instructions | .instructions.md | Auto (glob match) | Workspace / User | VS Code |
| 2 | Prompt Files | .prompt.md | Manual (/name) | Workspace / User | VS Code |
| 3 | Custom Agents | .agent.md | Manual (picker) | Workspace / User | VS Code + GitHub |
| 4 | Agent Skills | SKILL.md | Auto (on-demand) | Workspace / User | Cross-agent standard |
| 5 | MCP Servers | mcp.json | Auto (on start) | Workspace / User | MCP standard |
| 6 | Hooks | *.json | Auto (on event) | Workspace / User | VS Code + Claude (Preview) |
| 7 | Agent Plugins | marketplace | Auto (on install) | User | VS Code + CLI (Preview) |
Comparison: Instructions vs Skills vs Agents vs Prompts
| Dimension | Instructions | Skills | Agents | Prompts |
|---|
| Purpose | Coding rules/standards | Specialized capabilities | AI personas with tools | Reusable task commands |
| Contains tools? | No | No (references only) | Yes (tool list) | Yes (tool list) |
| Always loaded? | Yes (via glob) | No (on-demand) | No (manual select) | No (manual /invoke) |
| Can include scripts? | No | Yes (scripts/) | No | No |
| Can include resources? | No | Yes (references/, assets/) | No | No |
| Context cost | ~300-600 tok (est.) | ~500-2000 tok (est.) | ~500-1500 tok (est.) | ~200-500 tok (est.) |
| Portability | VS Code only | Open standard | VS Code + GitHub | VS Code only |
Token estimates are approximate. Run the context-optimizer skill for measured profiling.
How They Interact
- Tool list priority: Prompt tools > Agent tools > Default agent tools
- Instruction combining: Multiple instruction files are merged (no guaranteed order)
- Skill progressive loading: Discovery (name+description) → Instructions (SKILL.md body) → Resources (references/)
- Agent + Skill: Agents can reference skills via "Read
.github/skills/{name}/SKILL.md"
- MCP tools: Available to agents and prompts via their
tools list
Existing Enforcement Rules
These instruction files auto-load for matching files. This skill references but does NOT duplicate them:
| Instruction File | Glob | Enforces |
|---|
agent-authoring.instructions.md | **/*.agent.md, **/*.prompt.md | Agent authoring + research-first mandate |
agent-skills.instructions.md | **/.github/skills/**/SKILL.md | Skill frontmatter, body limits |
instructions.instructions.md | **/*.instructions.md | Instruction file format, applyTo rules |
context-optimization.instructions.md | Agents, skills, instructions | Context budget, hand-off rules |
Reference Index
Load only the reference file relevant to your current task:
Do NOT load all references. Most tasks need only 1-2 reference files.
Decision tree questions and mechanism comparisons can be answered from this SKILL.md alone.
Freshness
Content sourced from official VS Code docs (2026-03-08). Each reference file includes
a "Verify Freshness" section with the URL to check for updates.
Freshness checks are part of the Quarterly Context Audit in AGENTS.md.
