GitHub Copilot Customization Guide

When to Use
Instructions, Prompts, Skills & Agents

A complete reference for choosing the right customization type — so Copilot always knows your project, your standards, and your workflow.

Quick Decision Tree

Start here when deciding which customization type to use

1

Should this apply to EVERY interaction?

Think: coding standards, project conventions, response style preferences

YES →

Use: .github/copilot-instructions.md

Always loaded, applies universally across the entire repository

2

Should it apply only to SPECIFIC file types or directories?

Think: Python rules for .py files, React conventions for components/

YES →

Use: .github/instructions/*.instructions.md

Conditionally loaded based on applyTo glob patterns

3

Is it a REUSABLE task you'll invoke manually?

Think: scaffolding components, generating tests, code reviews

YES →

Use: .github/prompts/*.prompt.md

Loaded only when you type /prompt-name

4

Is it a COMPLEX workflow with scripts/resources?

Think: debugging CI/CD, security reviews, multi-step processes

YES →

Use: .github/skills/*/SKILL.md

Auto-loaded when description matches, includes bundled resources

5

Is it a PERSISTENT persona for specific workflows?

Think: "Frontend Expert", "Security Reviewer", "Bug Hunter"

YES →

Use: Custom Agent

Explicitly selected, orchestrates multiple skills and tools

Always Active

Repository Instructions

.github/copilot-instructions.md

Universal standards, tech stack, coding style, response preferences
File Match

Path-Specific Instructions

.github/instructions/*.instructions.md

Language rules, area conventions, test patterns via applyTo globs
On Command

Prompt Files

.github/prompts/*.prompt.md

Scaffolding, reviews, documentation generation — invoke with /name
Semantic Match

Agent Skills

.github/skills/*/SKILL.md

CI/CD, security, complex processes with bundled scripts & references
Explicit Select

Custom Agents

UI Configuration

Frontend Expert, Bug Hunter — persistent personas for entire sessions

Pro Tip

Path-specific instructions combine with repository-wide instructions. Editing Button.tsx? Both copilot-instructions.md and react.instructions.md are loaded together.

📁 Type 1 Always Active

Repository-Wide Instructions

When to Use

Project Overview

"Copilot doesn't understand our architecture" → Explain tech stack, folder structure, service communication

Coding Standards

"Generated code doesn't follow our conventions" → Naming, code style, linting rules

Build/Test Commands

"Copilot suggests wrong build commands" → Build, test, deploy, common commands

Response Style

"Copilot's answers are too verbose" → Response length, formatting, tone

Properties

Loading

Always Automatic

Scope

Entire repository

Best For

Universal standards

Priority

Medium

.github/copilot-instructions.md — E-commerce Platform Example 
# .github/copilot-instructions.md

# Project Overview
Multi-tenant e-commerce platform built with Next.js, TypeScript, and Prisma.
Microservices architecture: API Gateway → Services → PostgreSQL.

# Tech Stack
- Frontend: Next.js 14, React 18, Tailwind CSS
- Backend:  Node.js, Express, Prisma ORM
- Database: PostgreSQL 15
- Testing:  Jest, React Testing Library, Playwright

# Universal Coding Standards
- Use TypeScript strict mode
- All functions must have JSDoc comments
- Prefer async/await over promises
- Use early returns for error handling
- Follow Airbnb style guide

# Build Commands
- Development: `npm run dev`
- Build:       `npm run build`
- Test:        `npm test`
- Lint:        `npm run lint`

# Response Preferences
- Keep responses concise (under 10 lines when possible)
- Show code examples before explanations
- Use TypeScript, not JavaScript
🎯 Type 2 File Match

Path-Specific Instructions

Language-Specific

Python vs TypeScript

Separate instruction files per language

Frontend vs Backend

API vs UI patterns

src/api/ vs src/components/

Testing

**/*.test.* files

RTL assertions, test patterns

Legacy Code

legacy/ folder

Bug fixes only, no refactoring

Monorepo examples — react + python + testing 
# .github/instructions/react.instructions.md
---
applyTo: "src/components/**/*.tsx,src/pages/**/*.tsx"
---

# React Component Guidelines
- Use functional components with hooks (no class components)
- Prop types with TypeScript interfaces
- Tailwind for styling (no CSS modules)
- React.memo for performance-sensitive components
- Accessibility: all interactive elements need aria-labels


# .github/instructions/python-api.instructions.md
---
applyTo: "services/api/**/*.py"
---

# Python API Guidelines
- FastAPI for all endpoints
- Pydantic models for request/response validation
- async def for all routes
- Dependency injection for database connections
- OpenAPI documentation with detailed descriptions


# .github/instructions/testing.instructions.md
---
applyTo: "**/__tests__/**/*.ts,**/*.test.tsx,**/*.spec.py"
---

# Testing Standards
- Use React Testing Library (no Enzyme)
- Prefer data-testid over class selectors
- Mock external services and APIs
- Test user-visible behavior, not implementation
- Each test should be independent
⚡ Type 3 On Command

Prompt Files

/new-component

Component Scaffolding

React components with tests, consistent structure

/security-review

Code Reviews

Security/performance review checklist

/generate-docs

Documentation

Generate API docs in specific format

/create-tests

Test Generation

Unit tests with arrange-act-assert pattern

new-react-component.prompt.md 
---
agent: 'agent'
          model: GPT-5.2
description: 'Generate a new React component with tests'
---

# Create React Component
Generate a new React component:

Component Name: ${input:componentName:Enter component name}
Component Type: ${input:componentType:atom/molecule/organism}

Requirements:
1. Create in src/components/${input:componentType}s/
2. TypeScript with strict typing
3. Props interface
4. JSDoc comments
5. Create test file with RTL
6. Include Storybook story

Files to create:
- ${input:componentName}.tsx
- ${input:componentName}.test.tsx
- ${input:componentName}.stories.tsx
api-security-review.prompt.md 
---
agent: 'agent'
description: 'Security review for API endpoints'
---

# API Security Review
Review the selected API code for vulnerabilities:

1. Authentication/Authorization
   - Proper token validation
   - Role-based access control
   - Session management

2. Input Validation
   - SQL injection risks
   - XSS vulnerabilities
   - Command injection

3. Data Exposure
   - Sensitive data in responses
   - Error message information leakage
   - Logging of secrets

4. Rate Limiting
   - Endpoint protection
   - DDoS mitigation

Provide line numbers and remediation steps.

In Copilot Chat, type /new-react-component and you'll be prompted for the component name and type. The prompt file guides Copilot to generate everything according to your standards.

🎓 Type 4 Semantic Match

Agent Skills

CI/CD Debugging

github-actions-debugging

Multi-step log analysis and fixes

Database Migrations

database-migration

Migration scripts, rollback procedures

Performance

performance-analyzer

Profiling scripts, benchmark data

Security

security-audit

Scanning tools, vulnerability databases

.github/skills/github-actions-debugging/SKILL.md 
---
name: github-actions-debugging
description: Debug failing GitHub Actions workflows. Use when
  CI/CD fails, builds break, or Actions need troubleshooting.
---

# Debugging Process

1. Identify the failure
   - Check workflow run status
   - Identify failed job and step
   - Review error messages

2. Analyze logs
   - Use scripts/extract-error.sh to parse logs
   - Check references/common-errors.md
   - Check environment variables and secrets

3. Common Issues & Fixes
   
   Issue: Missing dependencies
   - Check package.json/requirements.txt changes
   - Run `scripts/validate-deps.sh`

   Issue: Permission errors
   - Check GITHUB_TOKEN permissions
   - Use `scripts/check-permissions.sh`

4. Fix and validate
   - Apply fix locally first
   - Test with act (GitHub Actions local runner)
   - Push and monitor workflow

# Available Resources
- scripts/extract-error.sh    - Parse workflow logs
- scripts/check-permissions.sh - Validate token perms
- references/common-errors.md  - Known issues

Directory Structure 

.github/skills/
└── github-actions-debugging/
    ├── SKILL.md
    ├── scripts/
    │   ├── extract-error.sh
    │   ├── check-permissions.sh
    │   └── validate-deps.sh
    ├── references/
    │   ├── common-errors.md
    │   ├── workflow-patterns.md
    │   └── test-data/
    └── examples/
        └── fixed-workflow.yml

How it activates

1. Query is semantically matched
2. SKILL.md loads automatically
3. Scripts become executable
4. References are available as context

Key Difference from Prompts

Skills are automatic and include bundled resources. Prompts are manual and are just text templates.

🤖 Type 5 Explicit Select

Custom Agents

Frontend Expert

React/TypeScript/Accessibility specialist

Bug Hunter

Quality and edge case focus

Security Reviewer

Security-focused code examination

Mentor

Onboarding junior developers

Frontend Expert — Custom Agent Configuration 
## Behavior
You are a frontend development expert specializing in:
- React 18+ best practices
- TypeScript strict mode
- Web accessibility (WCAG 2.1)
- Performance optimization
- Modern CSS (Tailwind/CSS Modules)

## Approach
1. Always consider component reusability
2. Prioritize accessibility in every suggestion
3. Optimize for performance (lazy loading, memoization)
4. Use semantic HTML
5. Consider mobile-first responsive design

## When helping with code:
- Suggest TypeScript interfaces for props
- Add aria-labels and roles
- Recommend React.memo for heavy components
- Point out potential accessibility issues
- Suggest Lighthouse audits for performance

## Skills to use:
- react-component-generator
- accessibility-checker
- performance-analyzer

Unlike skills that activate automatically for specific tasks, agents are personas you select that maintain consistent behavior across an entire session. They can orchestrate multiple skills and have persistent priorities.

Real-World Complete Setup

SaaS Platform with Microservices

Repository Structure 
.github/
├── copilot-instructions.md    # ALWAYS LOADED
│
├── instructions/               # CONDITIONAL
│   ├── python-api.instructions.md
│   ├── react-frontend.instructions.md
│   ├── testing.instructions.md
│   └── migrations.instructions.md
│
├── prompts/                    # MANUAL /command
│   ├── new-api-endpoint.prompt.md
│   ├── new-component.prompt.md
│   ├── generate-migration.prompt.md
│   └── code-review.prompt.md
│
└── skills/                     # AUTOMATIC semantic
    ├── github-actions-debug/
    │   ├── SKILL.md
    │   ├── scripts/
    │   └── references/
    ├── performance-optimization/
    │   ├── SKILL.md
    │   ├── scripts/
    │   └── benchmarks/
    └── security-audit/
        ├── SKILL.md
        ├── scripts/
        └── references/

Usage Scenarios

1 Adding New API Endpoint

copilot-instructions.md (always)
python-api.instructions.md (file is .py)
Type /new-api-endpoint for scaffolding

2 Debugging Failed CI

copilot-instructions.md (always)
github-actions-debug skill (semantic match)
Can execute scripts, reference docs

3 Building React Component

copilot-instructions.md (always)
react-frontend.instructions.md (file is .tsx)
Select "Frontend Expert" agent for session

4 Writing Tests

copilot-instructions.md (always)
testing.instructions.md (file is .test.tsx)
react-frontend.instructions.md (also .tsx)

Complete Comparison

All five types side by side

Feature Repo Instructions Path-Specific Prompt Files Skills Custom Agents
File Pattern copilot-instructions.md *.instructions.md *.prompt.md */SKILL.md UI config
Activation Always Active File Match Manual (/name) Semantic Match Explicit Select
Scope All files in repo Matching paths only Current task Relevant workflows Entire session
Can Include Text only Text only Text + variables Text + scripts + files Config + skills
Best For Universal standards Area-specific rules Repeated templates Complex workflows Persistent personas
Team Sharing ✅ Version control ✅ Version control ✅ Version control ✅ Version control ⚠️ Export/import

Final Decision Matrix

Ask yourself these questions

Question
Yes → Use This
No → Consider This
Does it apply to EVERY file/interaction?
copilot-instructions.md
→ Next question
Does it apply only to specific file types/paths?
*.instructions.md + applyTo
→ Next question
Will I invoke it repeatedly as a command?
*.prompt.md as /command
→ Next question
Does it need scripts or bundled resources?
SKILL.md + resources
→ Next question
Is it a multi-step complex workflow?
SKILL.md
→ Next question
Do I want a persistent persona for the session?
Custom Agent
Use simpler option above

Quick Reference Cheat Sheet

Always On

.github/copilot-instructions.md

Universal standards, tech stack, response style

File-Specific

.github/instructions/*.instructions.md

Language rules, area conventions, test patterns

On Command

.github/prompts/*.prompt.md

Scaffolding, reviews, doc generation

Smart Workflows

.github/skills/*/SKILL.md

CI/CD, security, complex processes

Personas

Custom Agents (UI)

Frontend Expert, Bug Hunter, roles