copilot-customization
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.
git clone --depth 1 https://github.com/jonathan-vella/apex /tmp/copilot-customization && cp -r /tmp/copilot-customization/.archive/_archived_skills/copilot-customization ~/.claude/skills/copilot-customizationSKILL.md
# 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
```text
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
1. **Tool list priority**: Prompt tools > Agent tools > Default agent tools
2. **Instruction combining**: Multiple instruction files are merged (no guaranteed order)
3. **Skill progressive loading**: Discovery (name+description) → Instructions (SKILL.md body) → Resources (references/)
4. **Agent + Skill**: Agents can reference skills via "Read `.github/skills/{name}/SKILL.md`"
5. **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:
| Reference | When to Load |
| ----------------------------------------------------------- | ------------------------------------------------------------------ |
| [custom-instructions.md](references/custom-instructions.md) | Creating/debugging `.instructions.md` or `copilot-instructions.md` |
| [prompt-files.md](references/prompt-fileGuidance for instrumenting webapps with Azure Application Insights. Provides telemetry patterns, SDK setup, and configuration references. WHEN: how to instrument app, App Insights SDK, telemetry patterns, what is App Insights, Application Insights guidance, instrumentation examples, APM best practices.
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
Configure Azure API Management as an AI Gateway for AI models, MCP tools, and agents. WHEN: semantic caching, token limit, content safety, load balancing, AI model governance, MCP rate limiting, jailbreak detection, add Azure OpenAI backend, add AI Foundry model, test AI gateway, LLM policies, configure AI backend, token metrics, AI cost control, convert API to MCP, import OpenAPI to gateway.
ROUTING SKILL — delegates to specialized diagram skills. USE FOR: any diagram request when the caller does not know which tool to use. Routes to drawio, python-diagrams, or mermaid based on diagram type.
Build and deploy GitHub Copilot SDK apps to Azure. WHEN: build copilot app, create copilot app, copilot SDK, @github/copilot-sdk, scaffold copilot project, copilot-powered app, deploy copilot app, host on azure, azure model, BYOM, bring your own model, use my own model, azure openai model, DefaultAzureCredential, self-hosted model, copilot SDK service, chat app with copilot, copilot-sdk-service template, azd init copilot, CopilotClient, createSession, sendAndWait, GitHub Models API.
Troubleshoot and resolve issues with Azure Messaging SDKs for Event Hubs and Service Bus. Covers connection failures, authentication errors, message processing issues, and SDK configuration problems. WHEN: event hub SDK error, service bus SDK issue, messaging connection failure, AMQP error, event processor host issue, message lock lost, send timeout, receiver disconnected, SDK troubleshooting, azure messaging SDK, event hub consumer, service bus queue issue, topic subscription error, enable logging event hub, service bus logging, eventhub python, servicebus java, eventhub javascript, servicebus dotnet, event hub checkpoint, event hub not receiving messages, service bus dead letter.
Provides canonical entity counts from count-manifest.json. Use when agents need to reference how many agents, skills, instructions, or validators exist. Prevents hard-coded counts. WHEN: agent count, skill count, how many agents, how many skills, entity inventory, project statistics.
Scaffolds new Agent Skills with SKILL.md frontmatter, folder structure, and bundled resources. USE FOR: create a skill, scaffold skill, new skill template, add agent capability. DO NOT USE FOR: Azure infrastructure, Bicep/Terraform code, architecture decisions.