Decoding GitHub Copilot Customizations

Work in Progress: This post is still being refined. Check back soon for updates.

You know GitHub Copilot can be customized. The official docs explain how to create instructions, prompts, agents, and skills.

But you're stuck at: "Which one do I use for THIS problem?"

This post gives you a decision framework: one question that leads you to the right layer.

The One-Question Framework

Ask yourself: "How often and in what context does this apply?"

Let's see how to recognize when you need each layer.

Layer 1: Instructions

Recognition Signals

• ✅ You repeat this in every chat
• ✅ It's a guideline or rule, not a task
• ✅ New developers need to know this

The 1-Second Test

"Is this a coding standard we always follow?" If yes → Instruction.

Example

# .github/copilot-instructions.md
- Use TypeScript strict mode
- Prefer async/await over promises
- Include JSDoc for public functions

Usage: Automatic (or manual include). Never invoke directly.

Boundaries

• ❌ NOT for specific tasks ("Create user profile component")
• ❌ NOT for conditional behavior ("Only plan, don't code")
• ❌ NOT for workflows ("Run tests then lint")

Best for: Coding practices, tech preferences, code review rules, commit message format.

Layer 2: Prompt Files

Recognition Signals

• ✅ You do this exact task 2-3+ times
• ✅ It's multi-step scaffolding
• ✅ You copy-paste the description

The 1-Second Test

"Do I keep explaining this same workflow?"

If yes → Prompt File.

Example

# .github/prompts/create-component.prompt.md
Create a React component with:
- TypeScript props interface
- JSDoc documentation
- Test file with React Testing Library
- Accessibility attributes

Usage: #create-component Button with label, onClick, loading

Boundaries

• ❌ NOT for general rules ("Use strict types")
• ❌ NOT for role-based behavior ("Only review code")
• ❌ NOT for workflows with scripts

Best for: Component scaffolding, endpoint generation, test creation, migration steps.

Layer 3: Custom Agents

Recognition Signals

• ✅ You need a specialist for a specific role
• ✅ You want limited scope (read-only, frontend-only)
• ✅ Different phases need different behavior (plan vs implement)

The 1-Second Test

"Do I need Copilot to act like a specialist with specific constraints?"

If yes → Custom Agent.

Example

# .github/agents/planner.agent.md
You are a planning specialist.

Constraints:
- READ-ONLY: Never write code
- Create implementation plans only
- Include risks and effort estimates

Usage: @planner how should we add authentication?

Result: Detailed plan, no code. Perfect for approval gates.

Boundaries

• ❌ NOT for task templates ("Generate component")
• ❌ NOT for general rules ("Use strict types")
• ❌ NOT for workflows with scripts

Best for: Planning phase, research mode, frontend-only work, security review, architecture analysis.

Layer 4: Agent Skills

Recognition Signals

• ✅ You have executable scripts/workflows
• ✅ It's a specialized capability (not just guidelines)
• ✅ You want portability across tools (VS Code, CLI, GitHub coding agent)

The 1-Second Test

"Does this workflow run actual scripts or tools?"

If yes → Agent Skill.

Example

.github/skills/pre-commit-check/
├── SKILL.md (instructions)
├── scripts/check_all.sh (executable)
└── references/quality-standards.md (docs)

Usage: @pre-commit-check

Result: Runs type checking, linting, tests, reports issues.

Boundaries

• ❌ NOT for task templates without scripts ("Generate component")
• ❌ NOT for guidelines ("Use strict types")
• ❌ NOT for behavior constraints ("Read-only mode")

Best for: Testing workflows, deployment checks, migration processes, code quality gates.

Note: Preview feature (VS Code Insiders). Open standard (agentskills.io).

Quick Reference: The Master Table

Decision Flowchart

Need Copilot to do something?
│
├─ Is it a STANDARD/RULE?
│  └─ Yes → Instruction
│
├─ Is it a TASK I repeat 2-3+ times?
│  └─ Yes → Prompt File
│
├─ Do I need a SPECIALIST ROLE?
│  └─ Yes → Custom Agent
│
└─ Does it RUN SCRIPTS?
   └─ Yes → Agent Skill

Summary

Choosing between Instructions, Prompt Files, Custom Agents, and Agent Skills doesn't have to be guesswork. The framework is simple: always-on standards become Instructions, repeatable tasks become Prompt Files, role-based behavior becomes Custom Agents, and executable workflows become Agent Skills. One question—"How often and in what context?"—is all you need to cut through the confusion and pick the right layer every time.

Resources

• gh-copilot-lab - Hands-on practice
• VS Code Docs - How to implement
• agentskills.io - Skills open standard