GitHub Copilot customization architecture
Choose the smallest customization that supplies the missing behavior. Inspect
the current workspace and active VS Code/Copilot version before writing files.
Selection model
| Need |
Choose |
Activation |
| Broad convention |
Instructions |
Automatic |
| File/task-specific convention |
.instructions.md |
Conditional |
| Focused reusable task |
Prompt file |
Manual slash command |
| Multi-step capability/resources |
Agent Skill |
Relevant task or slash command |
| Specialist persona/tool boundary |
Custom agent |
Selected/invoked role |
| Guaranteed lifecycle action |
Hook |
Deterministic event; preview |
| External live tools/data |
MCP |
Tool call after trust |
| Installable bundle |
Plugin |
Install/enable; preview |
Subagents are runtime delegation, not another file to create.
Workflow
- Inventory current instructions, prompts, skills, agents, hooks, MCP configs,
plugins, VS Code settings, and parent-repository discovery.
- State the repeated job, activation mode, workspace/user scope, required
capabilities, deterministic enforcement, and trust boundary.
- Route each requirement using the table. Split requirements whose activation,
authority, or verification differs.
- Build a collision map. Remove duplicate or contradictory rules; never rely
on instruction ordering.
- Assign least-privilege tools and explicit trust steps. Do not silently enable
executable hooks, servers, or plugins.
- Author through the matching specialized skill, then parse and test every
artifact before a VS Code smoke test.
Decision rules
- If guidance belongs in nearly every request, use repository instructions.
- If a person deliberately starts one task, use a prompt file; if Copilot must
discover a multi-step capability with resources, use a skill.
- If behavior must happen even when the model forgets, use a hook, not prose.
- If a role only needs read access, exclude edit and terminal tools.
- If a capability needs live external state, use a trusted tool/MCP server; do
not paste credentials or pretend durable instructions are current data.
- If several artifacts ship together, use a plugin only when installation and
trust are worth the packaging cost.
- Default to workspace scope. User scope requires an explicit cross-project job.
Read the format and scope map before choosing
locations. Use architecture recipes for a
multi-artifact design and verification before
declaring completion.
Completion
Deliver an artifact map with one owner per rule, explicit activation and trust
boundaries, no unresolved collisions, parsed files, offline executable checks,
and a recorded VS Code discovery plan. Mark hooks and plugins as preview and
host/model/tool identifiers as locally verified or unverified.
1---2name: github-copilot-customization-architecture3description: >-4 Use for designing, auditing, or refactoring a GitHub Copilot customization system in Visual Studio Code across instructions, prompt files, Agent Skills, custom agents, hooks, MCP servers, and plugins. Do not use merely to author one already-selected artifact or configure unrelated VS Code settings.5argument-hint: "[customization goal, repository, constraints, and current artifacts]"6---78# GitHub Copilot customization architecture910Choose the smallest customization that supplies the missing behavior. Inspect11the current workspace and active VS Code/Copilot version before writing files.1213## Selection model1415| Need | Choose | Activation |16|---|---|---|17| Broad convention | Instructions | Automatic |18| File/task-specific convention | `.instructions.md` | Conditional |19| Focused reusable task | Prompt file | Manual slash command |20| Multi-step capability/resources | Agent Skill | Relevant task or slash command |21| Specialist persona/tool boundary | Custom agent | Selected/invoked role |22| Guaranteed lifecycle action | Hook | Deterministic event; preview |23| External live tools/data | MCP | Tool call after trust |24| Installable bundle | Plugin | Install/enable; preview |2526Subagents are runtime delegation, not another file to create.2728## Workflow29301. Inventory current instructions, prompts, skills, agents, hooks, MCP configs,31 plugins, VS Code settings, and parent-repository discovery.322. State the repeated job, activation mode, workspace/user scope, required33 capabilities, deterministic enforcement, and trust boundary.343. Route each requirement using the table. Split requirements whose activation,35 authority, or verification differs.364. Build a collision map. Remove duplicate or contradictory rules; never rely37 on instruction ordering.385. Assign least-privilege tools and explicit trust steps. Do not silently enable39 executable hooks, servers, or plugins.406. Author through the matching specialized skill, then parse and test every41 artifact before a VS Code smoke test.4243## Decision rules4445- If guidance belongs in nearly every request, use repository instructions.46- If a person deliberately starts one task, use a prompt file; if Copilot must47 discover a multi-step capability with resources, use a skill.48- If behavior must happen even when the model forgets, use a hook, not prose.49- If a role only needs read access, exclude edit and terminal tools.50- If a capability needs live external state, use a trusted tool/MCP server; do51 not paste credentials or pretend durable instructions are current data.52- If several artifacts ship together, use a plugin only when installation and53 trust are worth the packaging cost.54- Default to workspace scope. User scope requires an explicit cross-project job.5556Read [the format and scope map](references/artifact-contracts.md) before choosing57locations. Use [architecture recipes](references/recipes-solutions.md) for a58multi-artifact design and [verification](references/verification.md) before59declaring completion.6061## Completion6263Deliver an artifact map with one owner per rule, explicit activation and trust64boundaries, no unresolved collisions, parsed files, offline executable checks,65and a recorded VS Code discovery plan. Mark hooks and plugins as preview and66host/model/tool identifiers as locally verified or unverified.
schattenspiegel