Customization decision framework reference
tech
prompt-engineering
github-copilot
reference
Consolidated decision framework for choosing between prompt files, instruction files, agents, skills, hooks, MCP servers, and Copilot Memory β with flowcharts, comparison matrices, and quick-reference tables.
Customization decision framework reference
GitHub Copilot offers ten customization mechanisms, each designed for a specific purpose. Choosing the wrong one wastes tokens, fragments your configuration, and confuses the model. This reference consolidates every decision table, comparison matrix, and flowchart from the series into a single lookup resource.
For the conceptual foundations behind each mechanism, see the corresponding concept article. This article answers one question: βwhich mechanism should I use?β
Table of contents
- πΊοΈ Master decision framework
- π Mechanism comparison matrix
- π Quick-reference lookup table
- βοΈ Written customizations: prompts vs. instructions vs. context files
- π€ Identity and capabilities: agents vs. skills
- βοΈ Enforcement: hooks vs. instructions
- π Tool sources: built-in vs. MCP vs. extensions
- π§ Persistent context: Memory vs. instructions vs. Spaces
- π³ Specialized decision trees
- π― Conclusion
- π References
πΊοΈ Master decision framework
Start here. This decision tree covers all ten mechanisms:
What are you trying to accomplish?
β
+- "I want rules that always apply to certain files"
β +- π Instruction file (.instructions.md) with applyTo pattern
β π Concept: 01.03 | π How-to: 05.00
β
+- "I want a reusable workflow I can run on demand"
β +- π Prompt file (.prompt.md) in .github/prompts/
β π Concept: 01.03 | π How-to: 03.00
β
+- "I want Copilot to know about my architecture/schemas/patterns"
β +- π Context file (.md) in .copilot/context/
β π Concept: 01.03
β
+- "I want a specialized AI persona with tool restrictions"
β +- π€ Agent file (.agent.md) in .github/agents/
β π Concept: 01.04 | π How-to: 04.00
β
+- "I want a cross-platform workflow with templates and scripts"
β +- π¦ Skill (SKILL.md) in .github/skills/
β π Concept: 01.05 | π How-to: 06.00
β
+- "I need to GUARANTEE something happens at a lifecycle point"
β +- πͺ Hook (.github/hooks/*.json)
β π Concept: 01.05 | π How-to: 09.00
β
+- "I need to connect to external APIs, databases, or services"
β +- π MCP server (mcp.json)
β π Concept: 01.06 | π How-to: 07.00
β
+- "I want my preferences to persist across sessions"
β +- π§ Let Copilot Memory learn them (automatic)
β π Concept: 01.09
β
+- "I want cross-project knowledge shared with my team"
β +- π Copilot Spaces
β π Overview: 01.01
β
+- "I need to embed Copilot in my own application"
+- π» GitHub Copilot SDK
π How-to: 14.00π Mechanism comparison matrix
Core properties
| Mechanism | File | Activation | Persistence | Identity change | Cross-platform |
|---|---|---|---|---|---|
| Prompt files | .prompt.md |
On-demand (/command) |
Single invocation | No | β VS Code only |
| Instruction files | .instructions.md |
Auto (file-pattern match) | Every matching request | No | β VS Code + GitHub.com |
| Context files | .md in .copilot/ |
On-demand (semantic search) | When retrieved | No | β VS Code + VS |
| Agents | .agent.md |
Agent picker | Entire session | Yes | β VS Code only |
| Skills | SKILL.md |
Auto (description match) or slash command | Single request | No | β VS Code, CLI, coding agent |
| Hooks | .json |
Lifecycle event | Deterministic | No | β VS Code, CLI, Claude Code |
| MCP servers | mcp.json |
Tool call at runtime | Session | No | β Any MCP client |
| Copilot Memory | (automatic) | Always present | Cross-session | No | β IDE, CLI, code review |
| Copilot Spaces | (GitHub.com) | Manual selection | Persistent | No | β GitHub-hosted |
| SDK | (code) | Application logic | App lifetime | No | β Any platform |
Capabilities
| Mechanism | Tool control | Resources | Can block execution | Can modify input | Handoffs |
|---|---|---|---|---|---|
| Prompt files | β Full | β None | β No | β No | β No |
| Instruction files | β None | β None | β No | β No | β No |
| Context files | β None | β None | β No | β No | β No |
| Agents | β Full | β None | β No | β No | β Full |
| Skills | β οΈ Limited | β Templates, scripts | β No | β No | β No |
| Hooks | β N/A | β None | β Yes | β Yes | β No |
| MCP servers | β Via tools | β Via resources | β No | β No | β No |
Token cost patterns
| Mechanism | Token cost pattern | Typical cost |
|---|---|---|
| Instruction files | Paid on every matching request | 200β1,000 tokens per file |
| Prompt files | Paid once per invocation | 500β2,000 tokens |
| Context files | Paid on demand (when retrieved) | Variable |
| Agents | Paid every request (identity layer) | 200β800 tokens |
| Skills | Progressive: ~50β100 (discovery) β 500β1,500 (on match) β variable (resources) | Minimal until activated |
| Hooks | Zero tokens (runs outside the prompt) | 0 tokens |
| MCP servers | Tool schemas in system prompt + results | 200+ tokens per tool |
| Copilot Memory | Injected into context window | Variable |
π Quick-reference lookup table
| Scenario | Use | File/Path |
|---|---|---|
| TypeScript coding standards | Instruction file | .github/instructions/typescript.instructions.md |
| Python PEP 8 conventions | Instruction file | .github/instructions/python-pep8.instructions.md |
| React component patterns | Instruction file | .github/instructions/react.instructions.md |
| Generate a migration script | Prompt file | .github/prompts/migration.prompt.md |
| Code review workflow | Prompt file | .github/prompts/code-review.prompt.md |
| Generate React form component | Prompt file | .github/prompts/react-form.prompt.md |
| API schema documentation | Context file | .copilot/context/api-schema.md |
| Architecture decision records | Context file | .copilot/context/architecture/ |
| Security reviewer persona | Agent file | .github/agents/security-reviewer.agent.md |
| Planning agent (read-only) | Agent file | .github/agents/planner.agent.md |
| Testing workflow with templates | Skill file | .github/skills/testing/SKILL.md |
| Deployment procedure with scripts | Skill file | .github/skills/deploy/SKILL.md |
| Block dangerous terminal commands | Hook | .github/hooks/security.json |
| Auto-format after edits | Hook | .github/hooks/formatting.json |
| Log all tool invocations | Hook | .github/hooks/audit.json |
| Query external database | MCP server | mcp.json + custom server |
| Access live monitoring data | MCP server | mcp.json + custom server |
| Personal coding style preferences | Copilot Memory | Automatic (learned) |
| Cross-project team standards | Copilot Spaces | GitHub.com configuration |
| Embed Copilot in desktop app | SDK | Application code |
| Complex code review + fixes | Agent β Agent handoff | Multiple .agent.md files |
| One-time refactoring | Chat command | Inline chat or /fix |
βοΈ Written customizations: prompts vs. instructions vs. context files
These three mechanisms all use Markdown, but serve fundamentally different purposes:
| Aspect | Prompt files | Instruction files | Context files |
|---|---|---|---|
| Purpose | Reusable tasks | Persistent rules | Project knowledge |
| Activation | On-demand (/command) |
Automatic (file pattern) | Semantic search retrieval |
| Assembly position | User prompt | System prompt | User prompt (when retrieved) |
| Tool control | β Full | β None | β None |
| Model routing | β
model: field |
β None | β None |
| Token cost | Once per use | Every matching request | On demand |
Decision tree
What kind of written guidance is it?
β
+- Rules that should apply silently to certain files
β +- π Instruction file with applyTo pattern
β
+- A workflow or task I run explicitly
β +- π Prompt file (invoked as /command)
β
+- Reference material about the project
β +- π Context file in .copilot/context/
β
+- General project-wide conventions
+- π copilot-instructions.md in .github/π Deep dive: Understanding prompt files, instructions, and context layers
π€ Identity and capabilities: agents vs. skills
Both extend Copilot beyond its defaults, but in fundamentally different ways:
| Aspect | Agents | Skills |
|---|---|---|
| What they do | Change the modelβs identity | Provide capabilities with resources |
| File | .agent.md |
SKILL.md + folder |
| Activation | Agent picker (or subagent) | Description match or slash command |
| Tool control | β Full β defines available tools | β οΈ Limited |
| Resources | β None | β Templates, scripts, examples |
| Cross-platform | β VS Code only | β VS Code, CLI, coding agent |
| Handoffs | β Orchestration between agents | β Not supported |
| Standard | VS Code-specific | Open (agentskills.io) |
Decision tree
Do you need to extend Copilot's capabilities?
β
+- Does it require a specific persona with tool restrictions?
β +- π€ Agent file (.agent.md)
β
+- Does it require templates, scripts, or examples?
β +- Does it need to work across VS Code, CLI, and coding agent?
β +- Yes β Skill (SKILL.md)
β +- No β Skill or Agent (either works)
β
+- Does it need multi-agent orchestration with handoffs?
β +- π€ Agent file with handoffs
β
+- Is it a one-time reusable workflow without resources?
+- π Prompt file (.prompt.md)π Deep dive: Understanding agents | Understanding skills and hooks
βοΈ Enforcement: hooks vs. instructions
Instructions suggest behavior. Hooks guarantee it:
| Aspect | Instructions | Hooks |
|---|---|---|
| Language | Natural language (Markdown) | Shell commands (JSON config) |
| Guarantee | Medium β model may ignore | High β your code runs deterministically |
| Can block execution | β No | β
Yes (PreToolUse) |
| Token cost | Tokens consumed | Zero tokens |
| Example | βAlways run tests after editingβ | PostToolUse script runs npm test |
When hooks beat instructions
| Need | Instruction approach | Hook approach | Winner |
|---|---|---|---|
| βDonβt delete production filesβ | βNever delete files matching prod*β | PreToolUse blocks rm on prod* |
Hook β |
| βFormat code after editsβ | βRun prettier after editingβ | PostToolUse runs npx prettier --write |
Hook β |
| βUse camelCase namingβ | βUse camelCase for all variablesβ | N/A β hooks canβt influence naming | Instruction β |
| βFollow React patternsβ | βUse functional components with hooksβ | N/A β hooks canβt guide coding style | Instruction β |
Rule of thumb: Use hooks for enforcement (blocking, formatting, logging). Use instructions for guidance (standards, patterns, style).
π Deep dive: Understanding skills, hooks, and lifecycle automation
π Tool sources: built-in vs. MCP vs. extensions
What capability do you need?
β
+- Already available as a built-in tool?
β +- Yes β Use built-in (no setup needed)
β
+- Available as a VS Code extension?
β +- Yes β Is VS Code-only acceptable?
β +- Yes β Install the extension
β +- No β Consider MCP for cross-platform
β
+- Available as a community MCP server?
β +- Yes β Install and configure in mcp.json
β
+- None of the above
+- Build your own MCP serverWhen to build an MCP server
| Need | Build MCP? | Alternative |
|---|---|---|
| Query external APIs/databases | β Yes | β |
| Real-time data (metrics, monitoring) | β Yes | β |
| Complex business logic | β Yes | β |
| Coding standards | β No | Instruction files |
| Workflow with templates | β No | Skills |
| Specialized persona | β No | Agent files |
| One-off task | β No | Prompt file |
π Deep dive: Understanding MCP and the tool ecosystem | π How-to: How to create MCP servers
π§ Persistent context: Memory vs. instructions vs. Spaces
Three mechanisms provide persistent context, each at a different scope:
| Aspect | Copilot Memory | Instruction files | Copilot Spaces |
|---|---|---|---|
| Scope | Personal (GitHub account) | Repository-specific | Cross-project (shareable) |
| Content | Learned preferences | Explicit rules | Curated knowledge |
| Activation | Automatic | Automatic (file pattern) | Manual selection |
| Population | Learned from interactions | Authored by developers | Assembled manually |
| Shared with team | β Personal only | β Via Git | β Via GitHub |
| Cross-repo | β Follows you | β Per repository | β Multi-repo |
| Best for | βHow I like to workβ | βHow we code in this projectβ | βWhat my team needs to knowβ |
Decision tree
What kind of persistent context is it?
β
+- Personal coding preferences
β +- π§ Copilot Memory (learned automatically)
β
+- Project-specific coding standards
β +- π Instruction files (.instructions.md)
β
+- Team knowledge shared across repos
β +- π Copilot Spaces
β
+- Project architecture and documentation
+- π Context files (.copilot/context/)π Deep dive: Understanding Copilot Memory
π³ Specialized decision trees
Choosing tools for your agent
What should your agent be able to do?
β
+- Read-only research β tools: ['codebase', 'filesystem', 'search']
+- Research + web β tools: ['codebase', 'fetch', 'web_search']
+- Code editing β tools: ['codebase', 'editor', 'filesystem']
+- Full local access β tools: ['codebase', 'editor', 'filesystem',
β 'search', 'usages', 'problems']
+- Orchestration β tools: ['agent', 'codebase']
+- Unrestricted β tools: [] (or omit field)π How-to: How to leverage tools in prompt orchestrations
Choosing a model
What's your top priority?
β
+- Speed and cost β GPT-4o mini / Gemini 2.0 Flash
+- Code generation β GPT-4o / Grok Code Fast 1
+- Complex reasoning β o3 / Claude Extended Thinking
+- Long context (>100K)β Claude Sonnet 4 / Gemini 2.0
+- Agentic workflows β Claude Opus 4.6 / GPT-5.4
+- Multimodal β Gemini 2.0 / GPT-4o
+- Local/private β Ollama via BYOKπ Deep dive: Understanding LLM models and model selection | π How-to: How to optimize prompts for specific models
Choosing an MCP implementation language
| If you need⦠| Choose⦠| Because⦠|
|---|---|---|
| Quick prototyping | Python (FastMCP) | Minimal boilerplate, decorator syntax |
| npm ecosystem access | TypeScript | Direct integration with npm packages |
| Enterprise integration | C# (.NET) | Strong typing, dependency injection |
| AI/ML capabilities | Python | Rich libraries (PyTorch, etc.) |
| Existing .NET codebase | C# (.NET) | Seamless integration |
| Maximum type safety | C# or TypeScript | Compile-time checking |
π How-to: How to create MCP servers for Copilot
π― Conclusion
Key principles
- Start simple. Instruction files and prompt files handle most needs. Add agents, skills, and hooks only when simpler options arenβt sufficient.
- One mechanism per concern. Donβt spread coding standards across prompts, instructions, and agent files. Pick the right one and consolidate.
- Hooks for enforcement, instructions for guidance. If you need a guarantee, use hooks. If you need influence, use instructions.
- Skills for portability, agents for orchestration. If it needs to work across platforms, use skills. If it needs tool control and handoffs, use agents.
- Memory for preferences, Spaces for knowledge. Personal preferences should be learned by Memory. Team knowledge should be curated in Spaces or instruction files.
- Token cost matters. Instructions inject on every request. Skills load progressively. Hooks cost zero tokens. Choose based on your token budget.
π References
Series concept articles:
- Understanding prompt files, instructions, and context layers β Written customization types
- Understanding agents, invocation, handoffs, and subagents β Agent identity and orchestration
- Understanding skills, hooks, and lifecycle automation β Portable capabilities and enforcement
- Understanding MCP and the tool ecosystem β External tool integration
- Understanding LLM models and model selection β Model families and selection
- Understanding Copilot Memory and persistent context β Cross-session persistence
Series how-to articles:
- How to structure content for Copilot prompt files
- How to structure content for Copilot agent files
- How to structure content for Copilot instruction files
- How to structure content for Copilot skills
- How to create MCP servers for Copilot
- How to use agent hooks for lifecycle automation
- How to leverage tools in prompt orchestrations